From 045dab22e04235fe294c5fa168a61a50d2ac48b4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 28 Mar 2025 12:59:44 -0700 Subject: [PATCH] fix that/which grammar --- xml/System.Buffers.Text/Base64Url.xml | 6 +- .../CommandLineBuilderExtensions.xml | 8 +- .../ParseArgument`1.xml | 2 +- .../CollectionEditor.xml | 126 +- .../IComponentChangeService.xml | 166 +- .../IEventBindingService.xml | 102 +- .../CustomTypeDescriptor.xml | 208 +- ...signerSerializationVisibilityAttribute.xml | 116 +- .../DisplayNameAttribute.xml | 26 +- .../ICustomTypeDescriptor.xml | 202 +- xml/System.ComponentModel/LicenseManager.xml | 162 +- .../PropertyFilterOptions.xml | 14 +- .../ConfigurationElement.xml | 2 +- .../ConfigurationElementCollection.xml | 550 +- .../SpatialEdmFunctions.xml | 2 +- xml/System.Data.Common/DbBatch.xml | 140 +- xml/System.Data.Common/DbCommand.xml | 16 +- xml/System.Data.Common/DbDataSource.xml | 94 +- xml/System.Data.Common/DbException.xml | 12 +- xml/System.Data.Common/DbParameter.xml | 2 +- .../DataAttribute.xml | 40 +- xml/System.Data.Odbc/OdbcParameter.xml | 2 +- xml/System.Data.OleDb/OleDbParameter.xml | 2 +- .../OracleParameter.xml | 768 +- .../OracleParameterCollection.xml | 156 +- .../DataServiceContext.xml | 2 +- .../ProjectedWrapperMany.xml | 2 +- xml/System.Data.SqlClient/SqlCommand.xml | 8 +- xml/System.Data.SqlClient/SqlParameter.xml | 2 +- xml/System.Data.SqlTypes/SqlDecimal.xml | 152 +- xml/System.Data.SqlTypes/SqlFileStream.xml | 4 +- xml/System.Data.SqlTypes/SqlSingle.xml | 148 +- xml/System.Data/DataRow.xml | 4 +- xml/System.Data/DataSet.xml | 8 +- xml/System.Data/DataTable.xml | 14 +- xml/System.Data/IDataRecord.xml | 256 +- .../GeoCoordinateWatcher.xml | 449 +- .../RecognizerInfo.xml | 516 +- .../SemanticResultKey.xml | 4 +- .../SemanticValue.xml | 1206 +-- .../SubsetMatchingMode.xml | 213 +- .../SpeechEventInfo.xml | 932 +- xml/System.Transactions/Enlistment.xml | 50 +- .../IEnlistmentNotification.xml | 134 +- xml/System.Xml.Schema/XmlSchema.xml | 4 +- xml/System.Xml.Schema/XmlSchemaCollection.xml | 540 +- .../XmlSchemaComplexType.xml | 230 +- xml/System.Xml.Schema/XmlSchemaSet.xml | 2 +- xml/System.Xml.Schema/XmlSchemaType.xml | 240 +- .../XmlAnyElementAttributes.xml | 74 +- .../XmlAttributeOverrides.xml | 168 +- .../XmlAttributes.xml | 2 +- .../XmlSerializationWriter.xml | 1172 +-- xml/System.Xml.XPath/XPathNamespaceScope.xml | 12 +- xml/System.Xml.XPath/XPathNavigator.xml | 7774 ++++++++--------- xml/System.Xml.Xsl/XslCompiledTransform.xml | 12 +- xml/System.Xml.Xsl/XslTransform.xml | 34 +- xml/System.Xml.Xsl/XsltException.xml | 22 +- xml/System.Xml/XmlConvert.xml | 2 +- xml/System.Xml/XmlDocument.xml | 4 +- xml/System.Xml/XmlNamespaceManager.xml | 526 +- xml/System.Xml/XmlNamespaceScope.xml | 2 +- xml/System.Xml/XmlNode.xml | 8 +- xml/System.Xml/XmlNodeReader.xml | 2 +- xml/System.Xml/XmlReaderSettings.xml | 2 +- xml/System.Xml/XmlValidatingReader.xml | 2 +- 66 files changed, 8915 insertions(+), 8947 deletions(-) diff --git a/xml/System.Buffers.Text/Base64Url.xml b/xml/System.Buffers.Text/Base64Url.xml index c074af9562e..5f70c246fb9 100644 --- a/xml/System.Buffers.Text/Base64Url.xml +++ b/xml/System.Buffers.Text/Base64Url.xml @@ -483,9 +483,9 @@ - The input span which contains binary data that needs to be encoded. - Encodes the span of binary data into unicode string represented as Base64Url ASCII chars. - A string which contains the result of the operation, i.e. the ASCII string in Base64Url. + The input span that contains binary data that needs to be encoded. + Encodes the span of binary data into Unicode string represented as Base64Url ASCII chars. + A string that contains the result of the operation, i.e. the ASCII string in Base64Url. This implementation of the base64url encoding omits the optional padding characters. diff --git a/xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml b/xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml index 136ac4c7415..62199c080e8 100644 --- a/xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml +++ b/xml/System.CommandLine.Builder/CommandLineBuilderExtensions.xml @@ -191,12 +191,12 @@ The same instance of . POSIX conventions recommend that single-character options be allowed to be specified together after a single - prefix. When is set to , the following command lines are equivalent: - + > myapp -a -b -c > myapp -abc - + If an argument is provided after an option bundle, it applies to the last option in the bundle. When is set to , all of the following command lines are equivalent: > myapp -a -b -c arg @@ -600,7 +600,7 @@ A command line builder. - Enables the use of the [suggest] directive which when specified in command line input short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions. + Enables the use of the [suggest] directive, which, when specified in command-line input, short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command-line completions. The same instance of . The dotnet-suggest tool requires the suggest directive to be enabled for an application to provide completions. @@ -682,7 +682,7 @@ A command line builder. - Enables the use of a option (defaulting to the alias --version) which when specified in command line input will short circuit normal command handling and instead write out version information before exiting. + Enables the use of a option (defaulting to the alias --version), which, when specified in command-line input, short circuits normal command handling and instead write out version information before exiting. The same instance of . To be added. diff --git a/xml/System.CommandLine.Parsing/ParseArgument`1.xml b/xml/System.CommandLine.Parsing/ParseArgument`1.xml index 240ddfa6ebe..4e04c7278da 100644 --- a/xml/System.CommandLine.Parsing/ParseArgument`1.xml +++ b/xml/System.CommandLine.Parsing/ParseArgument`1.xml @@ -26,7 +26,7 @@ T - The type which the argument is to be parsed as. + The type that the argument is to be parsed as. The argument result. Performs custom parsing of an argument. diff --git a/xml/System.ComponentModel.Design/CollectionEditor.xml b/xml/System.ComponentModel.Design/CollectionEditor.xml index 7cdc55736f0..88efa2bad28 100644 --- a/xml/System.ComponentModel.Design/CollectionEditor.xml +++ b/xml/System.ComponentModel.Design/CollectionEditor.xml @@ -52,15 +52,15 @@ Provides a user interface that can edit most types of collections at design time. - to associate the with a property. - + to associate the with a property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/EditorAttributesExample/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/CollectionEditor/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/EditorAttributesExample/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/EditorAttributesExample/VB/class1.vb" id="Snippet1"::: + ]]> @@ -188,13 +188,13 @@ if it is permissible to remove this value from the collection; otherwise, . The default implementation always returns . - @@ -235,11 +235,11 @@ if it multiple collection members can be selected at the same time; otherwise, . By default, this returns . - @@ -278,11 +278,11 @@ Gets the data type of each item in the collection. The data type of the collection items. - @@ -327,11 +327,11 @@ Gets the data type of the collection object. The data type of the collection object. - @@ -458,15 +458,15 @@ Gets the data type that this collection contains. The data type of the items in the collection, or an if no property can be located on the collection. - 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. - - The default implementation of this method returns the data type of the `Item` property of the collection, if it exists. - + 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. + + The default implementation of this method returns the data type of the `Item` property of the collection, if it exists. + ]]> @@ -552,15 +552,15 @@ Gets the data types that this collection editor can contain. An array of data types that this collection can contain. - 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. - - The default implementation of this method returns the type of all the collection items in a Type array. - + 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. + + The default implementation of this method returns the type of all the collection items in a Type array. + ]]> @@ -840,7 +840,7 @@ An returned as an object. Returns a list containing the given object. - An which contains the individual objects to be created. + An that contains the individual objects to be created. To be added. @@ -919,11 +919,11 @@ Gets the Help keyword to display the Help topic or topic list for when the editor's dialog box Help button or the F1 key is pressed. The Help keyword to display the Help topic or topic list for when Help is requested from the editor. - @@ -962,11 +962,11 @@ Gets the available types of items that can be created for this collection. The types of items that can be created. - . If more than one type is returned, the collection editor UI provides a way to choose which item type to create. - + . If more than one type is returned, the collection editor UI provides a way to choose which item type to create. + ]]> @@ -1019,11 +1019,11 @@ Sets the specified array as the items of the collection. The newly created collection object or, otherwise, the collection indicated by the parameter. - diff --git a/xml/System.ComponentModel.Design/IComponentChangeService.xml b/xml/System.ComponentModel.Design/IComponentChangeService.xml index 6ab07238db7..eabbe7e8132 100644 --- a/xml/System.ComponentModel.Design/IComponentChangeService.xml +++ b/xml/System.ComponentModel.Design/IComponentChangeService.xml @@ -48,38 +48,38 @@ Provides an interface to add and remove the event handlers for events that add, change, remove or rename components, and provides methods to raise a or event. - provides an interface that can be used to indicate the methods that handle the following events: - -- , raised when a component is added. - -- , raised when a component is about to be added. - -- , raised when a component is changed. - -- , raised when a component is about to be changed. - -- , raised when a component is removed. - -- , raised when a component is about to be removed. - -- , raised when a component is renamed. - - Typically, the design environment raises these component add, change, remove, or rename events. Designers should call the methods of this interface when using objects to provide undo and redo functionality for design-time actions that affect components. More information is available in the documentation for . Generally, only the root designer handles these change notifications. - - This service also provides methods that raise a component changed event or component changing event. A or a component can indicate that a component has changed or is changing with the and methods, respectively. - - - -## Examples - This following example demonstrates how to use the interface to receive notifications about the addition of, removal of, and changes to components in design mode. - + provides an interface that can be used to indicate the methods that handle the following events: + +- , raised when a component is added. + +- , raised when a component is about to be added. + +- , raised when a component is changed. + +- , raised when a component is about to be changed. + +- , raised when a component is removed. + +- , raised when a component is about to be removed. + +- , raised when a component is renamed. + + Typically, the design environment raises these component add, change, remove, or rename events. Designers should call the methods of this interface when using objects to provide undo and redo functionality for design-time actions that affect components. More information is available in the documentation for . Generally, only the root designer handles these change notifications. + + This service also provides methods that raise a component changed event or component changing event. A or a component can indicate that a component has changed or is changing with the and methods, respectively. + + + +## Examples + This following example demonstrates how to use the interface to receive notifications about the addition of, removal of, and changes to components in design mode. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IComponentChangeServiceSample2/CPP/icomponentchangeserviceexample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IComponentChangeService/Overview/icomponentchangeserviceexample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/IComponentChangeServiceSample2/VB/icomponentchangeserviceexample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/IComponentChangeServiceSample2/VB/icomponentchangeserviceexample.vb" id="Snippet1"::: + ]]> @@ -128,11 +128,11 @@ Occurs when a component has been added. - @@ -177,11 +177,11 @@ Occurs when a component is in the process of being added. - @@ -226,14 +226,14 @@ Occurs when a component has been changed. - [!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. In order 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 by adding a which 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. + ]]> @@ -279,11 +279,11 @@ Occurs when a component is in the process of being changed. - @@ -328,11 +328,11 @@ Occurs when a component has been removed. - @@ -377,11 +377,11 @@ Occurs when a component is in the process of being removed. - @@ -426,11 +426,11 @@ Occurs when a component is renamed. - event when a component has been renamed. - + event when a component has been renamed. + ]]> @@ -492,15 +492,15 @@ The new value of the member. This is valid only if the member is not . Announces to the component change service that a particular component has changed. - event. - - Most designers that ship with the Windows SDK, as well as the Visual Studio design-time environment, typically raise this event for you when a component in a project is changed, so most of the time you do not need to explicitly call this method. The appropriate events are automatically raised when a is used to change a property value or components are added or removed from the container. - - Before calling , first call to indicate that a component is about to change, and make the change. Then call to raise the event. - + event. + + Most designers that ship with the Windows SDK, as well as the Visual Studio design-time environment, typically raise this event for you when a component in a project is changed, so most of the time you do not need to explicitly call this method. The appropriate events are automatically raised when a is used to change a property value or components are added or removed from the container. + + Before calling , first call to indicate that a component is about to change, and make the change. Then call to raise the event. + ]]> @@ -561,13 +561,13 @@ The member that is changing. This is if this change is not related to a single member. Announces to the component change service that a particular component is changing. - event. - - Most designers included with the Windows SDK, as well as the Visual Studio design-time environment, typically raise this event automatically; so most of the time, you do not need to explicitly call this method. The appropriate events are automatically raised when a is used to change a property value or components are added or removed from the container. - + event. + + Most designers included with the Windows SDK, as well as the Visual Studio design-time environment, typically raise this event automatically; so most of the time, you do not need to explicitly call this method. The appropriate events are automatically raised when a is used to change a property value or components are added or removed from the container. + ]]> diff --git a/xml/System.ComponentModel.Design/IEventBindingService.xml b/xml/System.ComponentModel.Design/IEventBindingService.xml index 01d3bea1537..f6890b38f7f 100644 --- a/xml/System.ComponentModel.Design/IEventBindingService.xml +++ b/xml/System.ComponentModel.Design/IEventBindingService.xml @@ -48,24 +48,24 @@ Provides a service for registering event handlers for component events. - , you must first obtain an for the event of the component you intend to link. The provides methods that can convert an to a which you can use to configure the event with an event handler method name. - - The object provides a method that you can use to obtain an containing objects for each event of a component. The and methods of the return a for each passed to either method. Each returned from or has a property type of string. You can set this string to a value that indicates the name of the event-handler method to link the event with using the method of the . - - - -## Examples - The following example demonstrates a designer that uses the to link a component's event with an event handler at design time when the custom shortcut menu command that the designer adds for the component is invoked. To use the example, compile it to a class library, add a reference from a Windows Forms project, add the component in the class library to the Toolbox by right-clicking the **Toolbox** and selecting **Customize Toolbox**, then choosing the class library and clicking **OK**, and add an instance of the EventControl to a Form. Then right-click the EventControl and click the Connect testEvent shortcut menu command. An empty event handler method is created and the EventControl's testEvent method is initialized to this event handler in the initialization code for the Form. - + , you must first obtain an for the event of the component you intend to link. The provides methods that can convert an to a , which you can use to configure the event with an event handler method name. + + The object provides a method that you can use to obtain an containing objects for each event of a component. The and methods of the return a for each passed to either method. Each returned from or has a property type of string. You can set this string to a value that indicates the name of the event-handler method to link the event with using the method of the . + + + +## Examples + The following example demonstrates a designer that uses the to link a component's event with an event handler at design time when the custom shortcut menu command that the designer adds for the component is invoked. To use the example, compile it to a class library, add a reference from a Windows Forms project, add the component in the class library to the Toolbox by right-clicking the **Toolbox** and selecting **Customize Toolbox**, then choosing the class library and clicking **OK**, and add an instance of the EventControl to a Form. Then right-click the EventControl and click the Connect testEvent shortcut menu command. An empty event handler method is created and the EventControl's testEvent method is initialized to this event handler in the initialization code for the Form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IEventBindingServiceExample/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IEventBindingService/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/IEventBindingServiceExample/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/IEventBindingServiceExample/VB/source.vb" id="Snippet1"::: + ]]> @@ -119,11 +119,11 @@ Creates a unique name for an event-handler method for the specified component and event. The recommended name for the event-handler method for this event. - @@ -171,11 +171,11 @@ Gets a collection of event-handler methods that have a method signature compatible with the specified event. A collection of strings. - @@ -275,11 +275,11 @@ Converts a set of event descriptors to a set of property descriptors. An array of objects that describe the event set. - has a of string. - + has a of string. + ]]> @@ -327,11 +327,11 @@ Converts a single event descriptor to a property descriptor. A that describes the event. - has a of string. - + has a of string. + ]]> @@ -387,11 +387,11 @@ if the code is displayed; otherwise, . - @@ -440,11 +440,11 @@ if the code is displayed; otherwise, . - @@ -495,11 +495,11 @@ if the code is displayed; otherwise, . - diff --git a/xml/System.ComponentModel/CustomTypeDescriptor.xml b/xml/System.ComponentModel/CustomTypeDescriptor.xml index b2258a88b58..1b2e1156fb6 100644 --- a/xml/System.ComponentModel/CustomTypeDescriptor.xml +++ b/xml/System.ComponentModel/CustomTypeDescriptor.xml @@ -56,11 +56,11 @@ Provides a simple default implementation of the interface. - , the class relies on a parent object of type supplied during construction. This allows classes that derive from to selectively override methods. - + , the class relies on a parent object of type supplied during construction. This allows classes that derive from to selectively override methods. + ]]> @@ -119,13 +119,13 @@ Initializes a new instance of the class. - constructor with a parameter that is `null`. - - All methods of a created with this constructor will return default values. - + constructor with a parameter that is `null`. + + All methods of a created with this constructor will return default values. + ]]> @@ -177,20 +177,20 @@ The parent custom type descriptor. Initializes a new instance of the class using a parent custom type descriptor. - methods will return default values. Otherwise, all methods will delegate to the methods of `parent`. - - Most methods return `null` by default. The following table shows the return values for the methods that do not return `null` by default. - -|Method|Default return value| -|------------|--------------------------| -||An empty attribute collection ().| -||The default instance.| -||An empty events collection ().| -||An empty property collection ().| - + methods will return default values. Otherwise, all methods will delegate to the methods of `parent`. + + Most methods return `null` by default. The following table shows the return values for the methods that do not return `null` by default. + +|Method|Default return value| +|------------|--------------------------| +||An empty attribute collection ().| +||The default instance.| +||An empty events collection ().| +||An empty property collection ().| + ]]> @@ -239,11 +239,11 @@ Returns a collection of custom attributes for the type represented by this type descriptor. An containing the attributes for the type. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -297,15 +297,15 @@ Returns the fully qualified name of the class represented by this type descriptor. A containing the fully qualified class name of the type this type descriptor is describing. The default is . - [!NOTE] -> is not a static method and thus, is not guaranteed to be thread-safe. - - If a parent custom type descriptor was passed to the constructor, the method will call the parent's corresponding method. - +> is not a static method and thus, is not guaranteed to be thread-safe. + + If a parent custom type descriptor was passed to the constructor, the method will call the parent's corresponding method. + ]]> @@ -356,11 +356,11 @@ Returns the name of the class represented by this type descriptor. A containing the name of the component instance this type descriptor is describing. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -417,11 +417,11 @@ Returns a type converter for the type represented by this type descriptor. A for the type represented by this type descriptor. The default is a newly created . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -514,11 +514,11 @@ Returns the event descriptor for the default event of the object represented by this type descriptor. The for the default event on the object represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -576,11 +576,11 @@ Returns the property descriptor for the default property of the object represented by this type descriptor. A for the default property on the object represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -651,11 +651,11 @@ Returns an editor of the specified type that is to be associated with the class represented by this type descriptor. An editor of the given type that is to be associated with the class represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -670,11 +670,11 @@ Returns a collection of event descriptors for the object represented by this type descriptor. - method returns a collection of event descriptors for the object this type descriptor is representing. An optional attribute array may be provided to filter the collection that is returned. If no parent is provided, the method will return . - + method returns a collection of event descriptors for the object this type descriptor is representing. An optional attribute array may be provided to filter the collection that is returned. If no parent is provided, the method will return . + ]]> @@ -722,11 +722,11 @@ Returns a collection of event descriptors for the object represented by this type descriptor. An containing the event descriptors for the object represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -795,13 +795,13 @@ Returns a filtered collection of event descriptors for the object represented by this type descriptor. An containing the event descriptions for the object represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -853,11 +853,11 @@ Returns a collection of property descriptors for the object represented by this type descriptor. - method returns a collection of property descriptors for the object this type descriptor is representing. An optional attribute array may be provided to filter the collection that is returned. If no parent is provided, the method will return . - + method returns a collection of property descriptors for the object this type descriptor is representing. An optional attribute array may be provided to filter the collection that is returned. If no parent is provided, the method will return . + ]]> @@ -911,11 +911,11 @@ Returns a collection of property descriptors for the object represented by this type descriptor. A containing the property descriptions for the object represented by this type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -985,13 +985,13 @@ Returns a filtered collection of property descriptors for the object represented by this type descriptor. A containing the property descriptions for the object represented by this type descriptor. The default is . - . - - If a parent custom type descriptor was passed into the constructor, the method will call the parent's corresponding method. - + . + + If a parent custom type descriptor was passed into the constructor, the method will call the parent's corresponding method. + ]]> @@ -1084,11 +1084,11 @@ Returns an object that contains the property described by the specified property descriptor. An that owns the given property specified by the type descriptor. The default is . - constructor, the method will call the parent's corresponding method. - + constructor, the method will call the parent's corresponding method. + ]]> @@ -1124,7 +1124,7 @@ Gets a value that indicates whether types are required to be registered through . To be added. - The default value is which means that the type descriptor has not declared whether or not it is compatible registered types. + The default value is , which means that the type descriptor has not declared whether or not it is compatible registered types. A type descriptor needs to implement this to return or if the feature switch 'System.ComponentModel.TypeDescriptor.RequireRegisteredTypes' is enabled. If is returned, then the type descriptor must also implement diff --git a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml index d53ed8a2037..ab716012b9a 100644 --- a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml +++ b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml @@ -59,28 +59,28 @@ Specifies the type of persistence to use when serializing a property on a component at design time. - , you can indicate whether the value for a property is , and should be persisted in initialization code, , and should not be persisted in initialization code, or consists of , which should have initialization code generated for each public, not hidden property of the object assigned to the property. - - Members that do not have a will be treated as though they have a with a value of . The values of a property marked as will be serialized, if possible, by a serializer for the type. To specify custom serialization for a particular type or property, use the . - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates the use of a set to . It persists the values of a public property of a user control, which can be configured at design time. To use the example, first compile the following code into a user control library. Next, add a reference to the compiled .dll file in a new Windows Application project. If you are using Visual Studio, the `ContentSerializationExampleControl` is automatically added to the **Toolbox**. - - Drag the control from the **Toolbox** to a form, and set the properties of the `DimensionData` object listed in the Properties window. When you view the code for the form, code will have been added to the `InitializeComponent` method of the parent form. This code sets the values of the control's properties to those which you have set in design mode. - + , you can indicate whether the value for a property is , and should be persisted in initialization code, , and should not be persisted in initialization code, or consists of , which should have initialization code generated for each public, not hidden property of the object assigned to the property. + + Members that do not have a will be treated as though they have a with a value of . The values of a property marked as will be serialized, if possible, by a serializer for the type. To specify custom serialization for a particular type or property, use the . + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates the use of a set to . It persists the values of a public property of a user control, which can be configured at design time. To use the example, first compile the following code into a user control library. Next, add a reference to the compiled .dll file in a new Windows Application project. If you are using Visual Studio, the `ContentSerializationExampleControl` is automatically added to the **Toolbox**. + + Drag the control from the **Toolbox** to a form, and set the properties of the `DimensionData` object listed in the Properties window. When you view the code for the form, code will have been added to the `InitializeComponent` method of the parent form. This code sets the values of the control's properties to those that you have set in design mode. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DesignerSerializationVisibilityAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -136,15 +136,15 @@ One of the values. Initializes a new instance of the class using the specified value. - and sets its value to . - + and sets its value to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DesignerSerializationVisibilityAttribute/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -189,11 +189,11 @@ Specifies that a serializer should serialize the contents of the property, rather than the property itself. This field is read-only. - property is set to . - + property is set to . + ]]> @@ -240,11 +240,11 @@ Specifies the default value, which is , that is, a visual designer uses default rules to generate the value of a property. This field is read-only. - . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . - + . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + ]]> @@ -390,11 +390,11 @@ Specifies that a serializer should not serialize the value of the property. This field is read-only. - property is set to the constant member . - + property is set to the constant member . + ]]> @@ -491,17 +491,17 @@ Gets a value indicating the basic serialization mode a serializer should use when determining whether and how to persist the value of a property. One of the values. The default is . - 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. - + 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. + :::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"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.Visibility Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.Visibility Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -549,13 +549,13 @@ Specifies that a serializer should be allowed to serialize the value of the property. This field is read-only. - . - + . + ]]> diff --git a/xml/System.ComponentModel/DisplayNameAttribute.xml b/xml/System.ComponentModel/DisplayNameAttribute.xml index db78cbd34a8..43bb274ce19 100644 --- a/xml/System.ComponentModel/DisplayNameAttribute.xml +++ b/xml/System.ComponentModel/DisplayNameAttribute.xml @@ -52,21 +52,21 @@ - Specifies the display name for a property, event, or public void method which takes no arguments. + Specifies the display name for a property, event, or public void method that takes no arguments. - uses reflection to search the public properties and public void methods that take no arguments. searches for the on each property and method and, if found, uses that string instead of the property or method name. - - - -## Examples - The following code example demonstrates using the class to change the name of a property called `MisnamedProperty` to `RenamedProperty` in a control. 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). - + uses reflection to search the public properties and public void methods that take no arguments. searches for the on each property and method and, if found, uses that string instead of the property or method name. + + + +## Examples + The following code example demonstrates using the class to change the name of a property called `MisnamedProperty` to `RenamedProperty` in a control. 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="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AttributesDemoControl/VB/attributesdemocontrol.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AttributesDemoControl/VB/attributesdemocontrol.vb" id="Snippet30"::: + ]]> diff --git a/xml/System.ComponentModel/ICustomTypeDescriptor.xml b/xml/System.ComponentModel/ICustomTypeDescriptor.xml index 295aa3ddbb2..12ca37610c0 100644 --- a/xml/System.ComponentModel/ICustomTypeDescriptor.xml +++ b/xml/System.ComponentModel/ICustomTypeDescriptor.xml @@ -45,18 +45,18 @@ Provides an interface that supplies dynamic custom type information for an object. - interface allows an object to provide type information about itself. Typically, this interface is used when an object needs dynamic type information. In contrast, the class provides static type information that is obtained from metadata. - - For example, is used in the .NET Framework to provide type information for COM objects. COM objects do not support properties or attributes. Therefore, the .NET Framework uses to implement properties and attributes for COM objects. - - To provide dynamic custom type information, a class can implement or derive from the class, which provides a simple implementation of this interface. - + interface allows an object to provide type information about itself. Typically, this interface is used when an object needs dynamic type information. In contrast, the class provides static type information that is obtained from metadata. + + For example, is used in the .NET Framework to provide type information for COM objects. COM objects do not support properties or attributes. Therefore, the .NET Framework uses to implement properties and attributes for COM objects. + + To provide dynamic custom type information, a class can implement or derive from the class, which provides a simple implementation of this interface. + > [!NOTE] -> There is no design-time support for data binding to objects that implement the interface. In addition, when binding to a runtime instance of , the public properties of the underlying type are ignored. - +> There is no design-time support for data binding to objects that implement the interface. In addition, when binding to a runtime instance of , the public properties of the underlying type are ignored. + ]]> @@ -106,13 +106,13 @@ Returns a collection of custom attributes for this instance of a component. An containing the attributes for this object. - if no custom attributes are specified for an object. - + if no custom attributes are specified for an object. + ]]> @@ -164,11 +164,11 @@ Returns the class name of this instance of a component. The class name of the object, or if the class does not have a name. - method. - + method. + ]]> @@ -217,11 +217,11 @@ Returns the name of this instance of a component. The name of the object, or if the object does not have a name. - @@ -276,11 +276,11 @@ Returns a type converter for this instance of a component. A that is the converter for this object, or if there is no for this object. - . - + . + ]]> @@ -315,11 +315,11 @@ Returns a type converter for this instance of a component that might be registered. A that is the converter for this object, or if there is no for this object. - . - + . + ]]> @@ -491,11 +491,11 @@ Returns an editor of the specified type for this instance of a component. An of the specified type that is the editor for this object, or if the editor cannot be found. - , but you can also use other types (for example, and ). - + , but you can also use other types (for example, and ). + ]]> @@ -553,13 +553,13 @@ Returns the events for this instance of a component. An that represents the events for this component instance. - if no properties are specified. This method should never return `null`. - + if no properties are specified. This method should never return `null`. + ]]> @@ -627,13 +627,13 @@ Returns the events for this instance of a component using the specified attribute array as a filter. An that represents the filtered events for this component instance. - is specified in the `attributes` array and the event does not have an instance of the class for that attribute, the returned array includes the event if the is the default event. - + is specified in the `attributes` array and the event does not have an instance of the class for that attribute, the returned array includes the event if the is the default event. + ]]> @@ -672,13 +672,13 @@ Returns the events for this instance of a component that might be registered. An that represents the events for this component instance. - if no properties are specified. This method should never return `null`. - + if no properties are specified. This method should never return `null`. + ]]> @@ -740,13 +740,13 @@ Returns the properties for this instance of a component. A that represents the properties for this component instance. - if no properties are specified. This method should never return `null`. - + if no properties are specified. This method should never return `null`. + ]]> @@ -814,15 +814,15 @@ Returns the properties for this instance of a component using the attribute array as a filter. A that represents the filtered properties for this component instance. - is specified in the `attributes` array and the property does not have an instance of the class for that attribute, the returned collection will include the property if the is the default property. - - For filtering rules, see . - + is specified in the `attributes` array and the property does not have an instance of the class for that attribute, the returned collection will include the property if the is the default property. + + For filtering rules, see . + ]]> @@ -862,13 +862,13 @@ Returns the properties for this instance of a component that might be registered. A that represents the properties for this component instance. - if no properties are specified. This method should never return `null`. - + if no properties are specified. This method should never return `null`. + ]]> @@ -918,19 +918,19 @@ Returns an object that contains the property described by the specified property descriptor. An that represents the owner of the specified property. - method retrieves the object that contains the property member that is described by parameter. Typically, this object is required for the and methods. - - This method should return an object that you can use as follows: - -``` -pd.GetValue(GetPropertyOwner(myPd)); -``` - - If `myPd` is `null`, your implementation of the interface should return the default object (typically, the base object that exposes the properties and attributes). - + method retrieves the object that contains the property member that is described by parameter. Typically, this object is required for the and methods. + + This method should return an object that you can use as follows: + +``` +pd.GetValue(GetPropertyOwner(myPd)); +``` + + If `myPd` is `null`, your implementation of the interface should return the default object (typically, the base object that exposes the properties and attributes). + ]]> @@ -963,7 +963,7 @@ pd.GetValue(GetPropertyOwner(myPd)); Gets a value that indicates whether types are required to be registered through . To be added. - The default value is which means that the type descriptor has not declared whether or not it is compatible registered types. + The default value is , which means that the type descriptor has not declared whether or not it is compatible registered types. A type descriptor needs to implement this to return either or if the feature switch 'System.ComponentModel.TypeDescriptor.RequireRegisteredTypes' is enabled. If is returned, then the type descriptor must also implement diff --git a/xml/System.ComponentModel/LicenseManager.xml b/xml/System.ComponentModel/LicenseManager.xml index 73d3a61c472..72306b82f2b 100644 --- a/xml/System.ComponentModel/LicenseManager.xml +++ b/xml/System.ComponentModel/LicenseManager.xml @@ -50,30 +50,30 @@ Provides properties and methods to add a license to a component and to manage a . This class cannot be inherited. - class provides the following `static` properties: and . The class also provides the following `static` methods: , , and . - - When you create a component that you want to license, you must do the following: - -1. Specify the by marking the component with a . - -2. Call or in the constructor of the component. throws a when it tries to create an instance without a valid license. does not throw an exception. - -3. Call on any license that is granted when the component is disposed or finalized. - - For more information on licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). - - - -## Examples - The following code example creates a licensed control using the method. It uses a that is implemented by the class. - + class provides the following `static` properties: and . The class also provides the following `static` methods: , , and . + + When you create a component that you want to license, you must do the following: + +1. Specify the by marking the component with a . + +2. Call or in the constructor of the component. throws a when it tries to create an instance without a valid license. does not throw an exception. + +3. Call on any license that is granted when the component is disposed or finalized. + + For more information on licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). + + + +## Examples + The following code example creates a licensed control using the method. It uses a that is implemented by the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic LicenseManager Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LicenseManager/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic LicenseManager Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic LicenseManager Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -160,11 +160,11 @@ Creates an instance of the specified type, given a context in which you can use the licensed instance. An instance of the specified type. - you specify as the `creationContext` parameter is used as the for the life of this . The method blocks all other threads in the from modifying the , allowing to behave as an atomic operation. - + you specify as the `creationContext` parameter is used as the for the life of this . The method blocks all other threads in the from modifying the , allowing to behave as an atomic operation. + ]]> @@ -243,11 +243,11 @@ Creates an instance of the specified type with the specified arguments, given a context in which you can use the licensed instance. An instance of the specified type with the given array of arguments. - you specify as the `creationContext` parameter is used as the for the life of this . This method blocks all other threads in the from modifying the , allowing to behave as an atomic operation. - + you specify as the `creationContext` parameter is used as the for the life of this . This method blocks all other threads in the from modifying the , allowing to behave as an atomic operation. + ]]> @@ -298,11 +298,11 @@ Gets or sets the current , which specifies when you can use the licensed object. A that specifies when you can use the licensed object. - , the user must give the context in which the is valid to the method. The returned by this property should be passed to all classes. - + , the user must give the context in which the is valid to the method. The returned by this property should be passed to all classes. + ]]> The property is currently locked and cannot be changed. @@ -415,13 +415,13 @@ if a valid license can be granted; otherwise, . - method returns `true` when the type is either not licensed, or is licensed and the license is valid. - - This method does not throw a when it cannot grant a valid . The method throws exceptions. - + method returns `true` when the type is either not licensed, or is licensed and the license is valid. + + This method does not throw a when it cannot grant a valid . The method throws exceptions. + ]]> @@ -495,15 +495,15 @@ if a valid can be granted; otherwise, . - method returns `true` when the `type` parameter is not licensed, or when it is licensed and the `license` parameter is valid. - - This method does not throw a when it cannot grant a valid . The method throws exceptions. - - If the `license` parameter is not `null` after this call, the object asking for a must dispose of the license by calling the method when the object is disposed of or finalized. - + method returns `true` when the `type` parameter is not licensed, or when it is licensed and the `license` parameter is valid. + + This method does not throw a when it cannot grant a valid . The method throws exceptions. + + If the `license` parameter is not `null` after this call, the object asking for a must dispose of the license by calling the method when the object is disposed of or finalized. + ]]> @@ -557,11 +557,11 @@ The object whose current context you want to lock. Prevents changes being made to the current of the given object. - to get the of an object. This method locks the , preventing the from being retrieved. - + to get the of an object. This method locks the , preventing the from being retrieved. + ]]> The context is already locked. @@ -609,11 +609,11 @@ The object whose current context you want to unlock. Allows changes to be made to the current of the given object. - to get the of an object. This method unlocks the , allowing the to be retrieved. - + to get the of an object. This method unlocks the , allowing the to be retrieved. + ]]> @@ -656,14 +656,14 @@ System.ComponentModel.LicenseUsageMode - Gets the which specifies when you can use the licensed object for the . + Gets the that specifies when you can use the licensed object for the . One of the values, as specified in the property. - value, it returns . - + value, it returns . + ]]> @@ -728,11 +728,11 @@ A that represents the type of object that requests the license. Determines whether a license can be granted for the specified type. - when a valid cannot be granted. The method does not throw an exception. - + when a valid cannot be granted. The method does not throw an exception. + ]]> A cannot be granted. @@ -798,13 +798,13 @@ Determines whether a license can be granted for the instance of the specified type. A valid . - when a valid cannot be granted. The method does not throw an exception. - - All objects asking for a must dispose of the license by calling the method when the object is disposed of or finalized. - + when a valid cannot be granted. The method does not throw an exception. + + All objects asking for a must dispose of the license by calling the method when the object is disposed of or finalized. + ]]> The type is licensed, but a cannot be granted. diff --git a/xml/System.ComponentModel/PropertyFilterOptions.xml b/xml/System.ComponentModel/PropertyFilterOptions.xml index 8b006bf7b78..5d365450cef 100644 --- a/xml/System.ComponentModel/PropertyFilterOptions.xml +++ b/xml/System.ComponentModel/PropertyFilterOptions.xml @@ -28,13 +28,13 @@ Specifies which properties should be reported by type descriptors, specifically the method. This enumeration is used to specify the value of the property. - for . - - Invalid and Valid are relevant only for attached properties. The validity of a property is determined by working with the following attributes: , , which define the intended scope of the attached property in the object tree once the XAML is loaded. Designer applications that populate property grids and include attached properties in the grid must examine the value or presence of these attributes and the relative position of the current element versus either a parent or child element that "owns" the attached property. The owner-setter relationship together with the attribute values and will define whether a given attached property that is set on an element is valid or invalid. - + for . + + Invalid and Valid are relevant only for attached properties. The validity of a property is determined by working with the following attributes: , , . They define the intended scope of the attached property in the object tree once the XAML is loaded. Designer applications that populate property grids and include attached properties in the grid must examine the value or presence of these attributes and the relative position of the current element versus either a parent or child element that "owns" the attached property. The owner-setter relationship together with the attribute values and will define whether a given attached property that is set on an element is valid or invalid. + ]]> diff --git a/xml/System.Configuration/ConfigurationElement.xml b/xml/System.Configuration/ConfigurationElement.xml index 306472388a7..cb7ae77c977 100644 --- a/xml/System.Configuration/ConfigurationElement.xml +++ b/xml/System.Configuration/ConfigurationElement.xml @@ -182,7 +182,7 @@ property makes it easy to determine which version of the .NET Framework 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. ]]> diff --git a/xml/System.Configuration/ConfigurationElementCollection.xml b/xml/System.Configuration/ConfigurationElementCollection.xml index bb9b78526a7..5d2a61a7f10 100644 --- a/xml/System.Configuration/ConfigurationElementCollection.xml +++ b/xml/System.Configuration/ConfigurationElementCollection.xml @@ -45,54 +45,54 @@ Represents a configuration element containing a collection of child elements. - represents a collection of elements within a configuration file. - + represents a collection of elements within a configuration file. + > [!NOTE] -> An element within a configuration file refers to a basic XML element or a section. A simple element is an XML tag with related attributes, if any. A simple element constitutes a section. Complex sections can contain one or more simple elements, a collection of elements, and other sections. - - You use the to work with a collection of objects. Implement this class to add collections of custom elements to a . - - - -## Examples - The following example shows how to use the . - - The first example consists of three classes: `UrlsSection`, `UrlsCollection` and `UrlConfigElement`. The `UrlsSection` class uses the to define a custom configuration section. This section contains a URL collection (defined by the `UrlsCollection` class) of URL elements (defined by the `UrlConfigElement` class). - +> An element within a configuration file refers to a basic XML element or a section. A simple element is an XML tag with related attributes, if any. A simple element constitutes a section. Complex sections can contain one or more simple elements, a collection of elements, and other sections. + + You use the to work with a collection of objects. Implement this class to add collections of custom elements to a . + + + +## Examples + The following example shows how to use the . + + The first example consists of three classes: `UrlsSection`, `UrlsCollection` and `UrlConfigElement`. The `UrlsSection` class uses the to define a custom configuration section. This section contains a URL collection (defined by the `UrlsCollection` class) of URL elements (defined by the `UrlConfigElement` class). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet1"::: - - This second code example uses the classes specified before. You combine these two examples in a console application project. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet1"::: + + This second code example uses the classes specified before. You combine these two examples in a console application project. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/usingconfigurationcollectionelement.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/usingconfigurationcollectionelement.vb" id="Snippet31"::: - - When you run the console application, an instance of the `UrlsSection` class is created and the following configuration elements are generated in the application configuration file: - -```xml - - -
- - - - - - - + +
+ + + + + + + - You can use a programmatic or a declarative (attributed) coding model to create a custom configuration element. - - The programmatic model requires that for each element attribute you create a property to get and set its value, and that you add it to the internal property bag of the underlying base class. - + You can use a programmatic or a declarative (attributed) coding model to create a custom configuration element. + + The programmatic model requires that for each element attribute you create a property to get and set its value, and that you add it to the internal property bag of the underlying base class. + The declarative model, also referred to as the attributed model, allows you to define an element attribute by using a property and configuring it with attributes. These attributes instruct the ASP.NET configuration system about the property types and their default values. ASP.NET can use reflection to obtain this information and then create the element property objects and perform the required initialization. @@ -139,11 +139,11 @@ Initializes a new instance of the class. - when your application needs to create a custom . - + when your application needs to create a custom . + ]]> @@ -179,11 +179,11 @@ The comparer to use. Creates a new instance of the class. - is used to set a comparer to use. For example, you can use a case-insensitive comparer to make the key case insensitive. - + is used to set a comparer to use. For example, you can use a case-insensitive comparer to make the key case insensitive. + ]]> @@ -235,13 +235,13 @@ Adds a to an instance when overridden in a derived class. - method to add a new to the collection. Override in a derived class if custom behavior is required when the element is added. - - When adding, an element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. - + method to add a new to the collection. Override in a derived class if custom behavior is required when the element is added. + + When adding, an element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. + ]]> @@ -280,21 +280,21 @@ The to add. Adds a configuration element to the . - method to add a new to the collection. Override it in a derived class if custom behavior is required when the element is added. - - When adding, an element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. - - - -## Examples - The following code example shows how to override the method and how to call it from an `Add` method. - + method to add a new to the collection. Override it in a derived class if custom behavior is required when the element is added. + + When adding, an element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. + + + +## Examples + The following code example shows how to override the method and how to call it from an `Add` method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet2"::: + ]]> @@ -340,13 +340,13 @@ to throw an exception if the specified is already contained in the ; otherwise, . Adds a configuration element to the configuration element collection. - exception if the specified object already exists in the collection. - - An element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. - + exception if the specified object already exists in the collection. + + An element is considered a duplicate only if the keys are identical but the values are different. Elements with identical keys and values are accepted silently because the elements do not compete. However, an element with an identical key but a different value cannot be added because there is no logic to determine which of the competing values should be honored. + ]]> The to add already exists in the and the parameter is . @@ -388,11 +388,11 @@ The to add. Adds a configuration element to the configuration element collection. - object to the at a specific index location. - + object to the at a specific index location. + ]]> @@ -432,25 +432,25 @@ Removes all configuration element objects from the collection. - method is called, it removes all objects from the collection. It also inserts a `clear` directive into the configuration file. - - - -## Examples - The following code example shows how to call the method. - + method is called, it removes all objects from the collection. It also inserts a `clear` directive into the configuration file. + + + +## Examples + The following code example shows how to call the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet3"::: + ]]> - The configuration is read-only. - + The configuration is read-only. + -or- - + A collection item has been locked in a higher-level configuration. @@ -502,21 +502,21 @@ Gets the configuration element at the specified index location. The at the specified index. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet8"::: + ]]> - is less than . - + is less than . + -or- - + There is no at the specified . @@ -559,19 +559,19 @@ Returns the configuration element with the specified key. The with the specified key; otherwise, . - method returns `null` if there is no object with the specified key in the collection. - - - -## Examples - The following code example shows how to call the method. - + method returns `null` if there is no object with the specified key in the collection. + + + +## Examples + The following code example shows how to call the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet9"::: + ]]> @@ -654,10 +654,10 @@ The key for the specified . To be added. - is less than . - + is less than . + -or- - + There is no at the specified . @@ -696,13 +696,13 @@ Indicates the index of the specified . The index of the specified ; otherwise, -1. - method. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet10"::: - + method. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet10"::: + ]]> @@ -787,19 +787,19 @@ The key of the to remove. Removes a from the collection. - method inserts a `` directive into the configuration file for the with the specified key. - - - -## Examples - The following code example shows how to call the method. - + method inserts a `` directive into the configuration file for the with the specified key. + + + +## Examples + The following code example shows how to call the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet3"::: + ]]> No with the specified key exists in the collection, the element has already been removed, or the element cannot be removed because the value of its is not . @@ -843,33 +843,33 @@ The index location of the to remove. Removes the at the specified index location. - method inserts a `` directive into the configuration file for the element at the specified index location. - + method inserts a `` directive into the configuration file for the element at the specified index location. + ]]> - The configuration is read-only. - + The configuration is read-only. + -or- - - is less than or greater than the number of objects in the collection. - + + is less than or greater than the number of objects in the collection. + -or- - - The object has already been removed. - + + The object has already been removed. + -or- - - The value of the object has been locked at a higher level. - + + The value of the object has been locked at a higher level. + -or- - - The object was inherited. - + + The object was inherited. + -or- - + The value of the object's is not or . @@ -941,19 +941,19 @@ Gets the type of the . The of this collection. - or an field. For more information, see . - - - -## Examples - The following code example shows how to get the property. - + or an field. For more information, see . + + + +## Examples + 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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet5"::: + ]]> @@ -1040,11 +1040,11 @@ When overridden in a derived class, creates a new . - method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. - + method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. + ]]> @@ -1081,19 +1081,19 @@ When overridden in a derived class, creates a new . A newly created . - method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. - - - -## Examples - The following code example shows how to override the method. - + method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. + + + +## Examples + The following code example shows how to override the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet6"::: + ]]> @@ -1133,18 +1133,18 @@ Creates a new when overridden in a derived class. A new with a specified name. - method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. - + method to create custom objects of a specific type. When a collection is loaded from the configuration file, is called to create individual elements. must be overridden in classes that derive from the class. + ]]> - If you create a custom collection that contains heterogeneous types, you must perform these steps: - -- Override the method. - + If you create a custom collection that contains heterogeneous types, you must perform these steps: + +- Override the method. + - Make sure that the method returns a string that identifies the type of the element you created by calling the method. @@ -1180,11 +1180,11 @@ Gets the name used to identify this collection of elements in the configuration file when overridden in a derived class. The name of the collection; otherwise, an empty string. The default is an empty string. - property to name a custom . - + property to name a custom . + ]]> @@ -1221,11 +1221,11 @@ if the collection has been cleared; otherwise, . The default is . - property to `true` causes a `` directive to be written to the configuration file when the collection is serialized. - + property to `true` causes a `` directive to be written to the configuration file when the collection is serialized. + ]]> The configuration is read-only. @@ -1304,14 +1304,14 @@ Gets the element key for a specified configuration element when overridden in a derived class. An that acts as the key for the specified . - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet7"::: + ]]> @@ -1348,8 +1348,8 @@ - Gets an which is used to iterate through the . - An which is used to iterate through the . + Gets an that is used to iterate through the . + An that is used to iterate through the . To be added. @@ -1423,11 +1423,11 @@ if the element exists in the collection; otherwise, . The default is . - method to provide custom behavior. - + method to provide custom behavior. + ]]> @@ -1468,11 +1468,11 @@ if the specified can be removed from this ; otherwise, . The default is . - before removing a collection element. - + before removing a collection element. + ]]> @@ -1514,11 +1514,11 @@ if any contained element has been modified; otherwise, . - method of any contained within a returns `true`, the method of the entire collection returns `true` as well. - + method of any contained within a returns `true`, the method of the entire collection returns `true` as well. + ]]> @@ -1556,11 +1556,11 @@ if the object is read only; otherwise, . - @@ -1640,13 +1640,13 @@ if the unrecognized element was deserialized successfully; otherwise, . The default is . - is called when an unrecognized configuration element is read from a configuration file. - - Override this method to provide custom handling of unrecognized configuration elements from a configuration file. The default return value, `false`, causes the configuration system to throw an exception. - + is called when an unrecognized configuration element is read from a configuration file. + + Override this method to provide custom handling of unrecognized configuration elements from a configuration file. The default return value, `false`, causes the configuration system to throw an exception. + ]]> The element specified in is the element. @@ -1729,11 +1729,11 @@ The representing the collection parent element, if any; otherwise, . Resets the to its unmodified state when overridden in a derived class. - method is to clear any modified elements a object contains and to set the modified elements to the values specified by their parent configuration file. If any element in the has child elements, is also called on those child elements. - + method is to clear any modified elements a object contains and to set the modified elements to the values specified by their parent configuration file. If any element in the has child elements, is also called on those child elements. + ]]> @@ -1773,11 +1773,11 @@ Resets the value of the property to when overridden in a derived class. - method determines whether the elements of this collection will be written to the configuration file when the configuration is updated. - + method determines whether the elements of this collection will be written to the configuration file when the configuration is updated. + ]]> @@ -1825,11 +1825,11 @@ if the was written to the configuration file successfully. - method writes the contents of the configuration elements contained in the collection and any nested elements they contain to the configuration file. Override to provide a custom write procedure out of the collection contents and nested elements. - + method writes the contents of the configuration elements contained in the collection and any nested elements they contain to the configuration file. Override to provide a custom write procedure out of the collection contents and nested elements. + ]]> One of the elements in the collection was added or replaced and starts with the reserved prefix "config" or "lock". @@ -1870,11 +1870,11 @@ Sets the property for the object and for all sub-elements. - method. - + method. + ]]> @@ -1988,13 +1988,13 @@ if an attempt to add a duplicate to this will cause an exception to be thrown; otherwise, . - value of the element is either or . - - Note that elements with identical keys and values are not considered duplicates, and are accepted silently. Only elements with identical keys but different values are considered duplicates. For more information, see the Remarks section for the method. - + value of the element is either or . + + Note that elements with identical keys and values are not considered duplicates, and are accepted silently. Only elements with identical keys but different values are considered duplicates. For more information, see the Remarks section for the method. + ]]> diff --git a/xml/System.Data.Common.CommandTrees.ExpressionBuilder.Spatial/SpatialEdmFunctions.xml b/xml/System.Data.Common.CommandTrees.ExpressionBuilder.Spatial/SpatialEdmFunctions.xml index 293e0eb7623..5692bec081a 100644 --- a/xml/System.Data.Common.CommandTrees.ExpressionBuilder.Spatial/SpatialEdmFunctions.xml +++ b/xml/System.Data.Common.CommandTrees.ExpressionBuilder.Spatial/SpatialEdmFunctions.xml @@ -1962,7 +1962,7 @@ - An expression that specifies the geometry value which should be tested for spatial validity. + An expression that specifies the geometry value that should be tested for spatial validity. Creates a that invokes the canonical 'IsValidGeometry' function with the specified argument, which must have an Edm.Geometry result type. The result type of the expression is Edm.Boolean. A new DbFunctionExpression that returns a Boolean value indicating whether is valid. To be added. diff --git a/xml/System.Data.Common/DbBatch.xml b/xml/System.Data.Common/DbBatch.xml index 5926065411d..889c80b36b0 100644 --- a/xml/System.Data.Common/DbBatch.xml +++ b/xml/System.Data.Common/DbBatch.xml @@ -31,14 +31,14 @@ - Represents a batch of commands which can be executed against a data source in a single round trip. Provides a base class for database-specific classes that represent command batches. + Represents a batch of commands that can be executed against a data source in a single round trip. Provides a base class for database-specific classes that represent command batches. - @@ -112,11 +112,11 @@ The precise semantics of batch execution vary across ADO.NET providers, especial Attempts to cancel the execution of a . - @@ -346,11 +346,11 @@ The precise semantics of batch execution vary across ADO.NET providers, especial Asynchronously disposes the batch object. A representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -383,14 +383,14 @@ The precise semantics of batch execution vary across ADO.NET providers, especial An instance of , specifying options for batch execution and data retrieval. - When overridden in a derived class, executes the batch against its connection, returning a which can be used to access the results. + When overridden in a derived class, executes the batch against its connection, returning a that can be used to access the results. A object. - can be used to advance the reader to the next result set. - + ]]> An error occurred while executing the batch. @@ -423,18 +423,18 @@ The precise semantics of batch execution vary across ADO.NET providers, especial One of the enumeration values that specifies options for batch execution and data retrieval. A token to cancel the asynchronous operation. - Providers should implement this method to provide a non-default implementation for overloads. - - The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property. - + Providers should implement this method to provide a non-default implementation for overloads. + + The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property. + This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -466,15 +466,15 @@ The precise semantics of batch execution vary across ADO.NET providers, especial Executes the batch against its connection object, returning the total number of rows affected across all the batch commands. The total number of rows affected across all the batch commands. - 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 by executing UPDATE, INSERT, or DELETE statements. - - Although 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 total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. - + 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 by executing UPDATE, INSERT, or DELETE statements. + + Although 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 total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. + ]]> @@ -502,18 +502,18 @@ The precise semantics of batch execution vary across ADO.NET providers, especial A token to cancel the asynchronous operation. - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. - - The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by will be communicated via the returned Task Exception property. - + This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. + + The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by will be communicated via the returned Task Exception property. + Do not invoke other methods and properties of the object until the returned Task is complete. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -546,14 +546,14 @@ The precise semantics of batch execution vary across ADO.NET providers, especial One of the enumeration values that specifies options for batch execution and data retrieval. - Executes the batch against its connection, returning a which can be used to access the results. + Executes the batch against its connection, returning a that can be used to access the results. A object. - can be used to advance the reader to the next result set. - + ]]> @@ -581,14 +581,14 @@ The precise semantics of batch execution vary across ADO.NET providers, especial To be added. - An asynchronous version of , which executes the batch against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the batch against its connection, returning a that can be used to access the results. A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + ]]> An error occurred while executing the batch. @@ -621,14 +621,14 @@ The precise semantics of batch execution vary across ADO.NET providers, especial One of the enumeration values that specifies options for batch execution and data retrieval. A token to cancel the asynchronous operation. - An asynchronous version of , which executes the batch against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the batch against its connection, returning a that can be used to access the results. A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + 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 . ]]> @@ -778,13 +778,13 @@ The precise semantics of batch execution vary across ADO.NET providers, especial Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error. The time in seconds to wait for the batch to execute. - is generated if the assigned property value is less than 0. - - Note to implementers: it's recommended that 0 mean no timeout. - + 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 644c7157042..f4aa2003a60 100644 --- a/xml/System.Data.Common/DbCommand.xml +++ b/xml/System.Data.Common/DbCommand.xml @@ -862,7 +862,7 @@ An instance of , specifying options for command execution and data retrieval. - Executes the command against its connection, returning a which can be used to access the results. + Executes the command against its connection, returning a that can be used to access the results. A object. To be added. An error occurred while executing the command. @@ -1134,7 +1134,7 @@ 4.2.0.0 - Executes the command against its connection, returning a which can be used to access the results. + Executes the command against its connection, returning a that can be used to access the results. ADO.NET Overview @@ -1176,7 +1176,7 @@ - Executes the command against its connection, returning a which can be used to access the results. + Executes the command against its connection, returning a that can be used to access the results. A object. To be added. ADO.NET Overview @@ -1223,7 +1223,7 @@ An instance of , specifying options for command execution and data retrieval. - Executes the command against its connection, returning a which can be used to access the results. + Executes the command against its connection, returning a that can be used to access the results. An object. To be added. ADO.NET Overview @@ -1235,7 +1235,7 @@ 4.1.0.0 - An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the command against its connection, returning a that can be used to access the results. - An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the command against its connection, returning a that can be used to access the results. Invokes with CancellationToken.None. A task representing the asynchronous operation. @@ -1343,7 +1343,7 @@ One of the enumeration values that specifies how the command should execute and how data should be retrieved. - An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the command against its connection, returning a that can be used to access the results. Invokes . A task representing the asynchronous operation. @@ -1402,7 +1402,7 @@ A token to cancel the asynchronous operation. - An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. + An asynchronous version of , which executes the command against its connection, returning a that can be used to access the results. Invokes . A task representing the asynchronous operation. diff --git a/xml/System.Data.Common/DbDataSource.xml b/xml/System.Data.Common/DbDataSource.xml index 1120ca37de0..57fd71adb6f 100644 --- a/xml/System.Data.Common/DbDataSource.xml +++ b/xml/System.Data.Common/DbDataSource.xml @@ -30,7 +30,7 @@ - Represents a data source which can be used to obtain open connections, and against which commands can be executed directly. + Represents a data source that can be used to obtain open connections, and against which commands can be executed directly. Unlike , which is purely a factory for provider-specific objects such as , hands out open connections to specific databases, encapsulating all the information needed to connect to a database. Depending on how the was configured, the connections it hands out may be pooled. @@ -101,9 +101,9 @@ Returns a that's ready for execution against the . A that's ready for execution against the . - ; their does not need to be set, and doing so will throw an exception. Since these batches have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. @@ -144,9 +144,9 @@ Returns a that's ready for execution against the . A that's ready for execution against the . - ; their does not need to be set, and doing so will throw an exception. Since these commands have no explicitly-managed connection, it is not possible to use them with transactions, and trying to set will throw an exception. To use a transaction, get a connection from and create a command against it. @@ -178,10 +178,10 @@ Returns a new, closed connection to the database represented by this . A new, closed connection to the database represented by this . - Returns a that's ready for execution against the . A that's ready for execution against the . - @@ -253,9 +253,9 @@ Returns a that's ready for execution against the . A that's ready for execution against the . - @@ -285,9 +285,9 @@ Returns a new, closed connection to the database represented by this . A new, closed connection to the database represented by this . - @@ -319,9 +319,9 @@ Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously. - represents a connection pool, disposing it should close all idle connections, and arrange for busy connections to be closed as soon as possible. ]]> @@ -354,9 +354,9 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Called by the Dispose() and Finalize() methods to release the managed and unmanaged resources used by the current instance of the class. - @@ -389,9 +389,9 @@ Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously. A task that represents the asynchronous dispose operation. - represents a connection pool, disposing it should close all idle connections, and arrange for busy connections to be closed as soon as possible. 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 . @@ -423,9 +423,9 @@ Performs application-defined tasks associated with freeing, releasing, or resetting managed resources asynchronously. A task that represents the asynchronous dispose operation. - @@ -455,13 +455,13 @@ Returns a new, open connection to the database represented by this . A new, open connection to the database represented by this . - @@ -497,13 +497,13 @@ Asynchronously returns a new, open connection to the database represented by this . A new, open connection to the database represented by this . - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -534,9 +534,9 @@ Returns a new, open connection to the database represented by this . A new, open connection to the database represented by this . - @@ -574,9 +574,9 @@ Asynchronously returns a new, open connection to the database represented by this . A new, open connection to the database represented by this . - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.Data.Common/DbException.xml b/xml/System.Data.Common/DbException.xml index 7afeb0721e0..3c11135c8fe 100644 --- a/xml/System.Data.Common/DbException.xml +++ b/xml/System.Data.Common/DbException.xml @@ -377,8 +377,8 @@ System.Data.Common.DbBatchCommand - If this was thrown when executing a , references the specific which triggered the exception. - The specific which triggered the exception. + If this was thrown when executing a , references the specific that triggered the exception. + The specific that triggered the exception. System.Data.Common.DbBatchCommand - When overridden in a derived class, if this was thrown when executing a , references the specific which triggered the exception. - The specific which triggered the exception. + When overridden in a derived class, if this was thrown when executing a , references the specific that triggered the exception. + The specific that triggered the exception. - For database providers which support it, contains a standard SQL 5-character return code indicating the success or failure of the database operation. The first 2 characters represent the class of the return code (e.g. error, success), while the last 3 characters represent the subclass, allowing detection of error scenarios in a database-portable way. + For database providers that support it, contains a standard SQL 5-character return code indicating the success or failure of the database operation. The first 2 characters represent the class of the return code (e.g. error, success), while the last 3 characters represent the subclass, allowing detection of error scenarios in a database-portable way. - For database providers which don't support it, or for inapplicable error scenarios, contains . + For database providers that don't support it, or for inapplicable error scenarios, contains . A standard SQL 5-character return code, or . diff --git a/xml/System.Data.Common/DbParameter.xml b/xml/System.Data.Common/DbParameter.xml index 429cd198e19..49c3b4dc136 100644 --- a/xml/System.Data.Common/DbParameter.xml +++ b/xml/System.Data.Common/DbParameter.xml @@ -668,7 +668,7 @@ System.Boolean - Gets or sets a value which indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. + Gets or sets a value that indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. if the source column is nullable; if it is not. diff --git a/xml/System.Data.Linq.Mapping/DataAttribute.xml b/xml/System.Data.Linq.Mapping/DataAttribute.xml index 7270075b601..c21b456b7a6 100644 --- a/xml/System.Data.Linq.Mapping/DataAttribute.xml +++ b/xml/System.Data.Linq.Mapping/DataAttribute.xml @@ -105,27 +105,25 @@ Gets or sets a private storage field to hold the value from a column. The name of the storage field. - _ -Public CustomerID As String -``` - -```csharp -[Column(Storage="_CustomerID")] -public string CustomerID -{ -} -``` - + _ +Public CustomerID As String +``` + +```csharp +[Column(Storage="_CustomerID")] +public string CustomerID +{ +} +``` + ]]> diff --git a/xml/System.Data.Odbc/OdbcParameter.xml b/xml/System.Data.Odbc/OdbcParameter.xml index f9090268a0f..e4ac698bab3 100644 --- a/xml/System.Data.Odbc/OdbcParameter.xml +++ b/xml/System.Data.Odbc/OdbcParameter.xml @@ -1230,7 +1230,7 @@ public void CreateOdbcParameter() System.Boolean - Gets or sets a value which indicates whether the source column is nullable. This lets correctly generate Update statements for nullable columns. + Gets or sets a value that indicates whether the source column is nullable. This lets correctly generate Update statements for nullable columns. if the source column is nullable; if it is not. diff --git a/xml/System.Data.OleDb/OleDbParameter.xml b/xml/System.Data.OleDb/OleDbParameter.xml index 887167261aa..7a59e9cbf01 100644 --- a/xml/System.Data.OleDb/OleDbParameter.xml +++ b/xml/System.Data.OleDb/OleDbParameter.xml @@ -1271,7 +1271,7 @@ public void CreateOleDbParameter() System.Boolean - Gets or sets a value which indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. + Gets or sets a value that indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. if the source column is nullable; if it is not. diff --git a/xml/System.Data.OracleClient/OracleParameter.xml b/xml/System.Data.OracleClient/OracleParameter.xml index 51c44e445a5..7484e55b4bd 100644 --- a/xml/System.Data.OracleClient/OracleParameter.xml +++ b/xml/System.Data.OracleClient/OracleParameter.xml @@ -40,39 +40,39 @@ Represents a parameter to an and optionally its mapping to a . This class cannot be inherited. - through the within the . These parameters are used to select data from the database and place the data in the . This example assumes that a and an have already been created by using the appropriate schema, commands, and connection. - + through the within the . These parameters are used to select data from the database and place the data in the . This example assumes that a and an have already been created by using the appropriate schema, commands, and connection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter/VB/source.vb" id="Snippet1"::: + ]]> @@ -128,14 +128,14 @@ OleDbDataReader reader = command.ExecuteReader(); One of the values. Initializes a new instance of the class that uses the parameter name and data type. - and sets some of its properties. - + and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter1/VB/source.vb" id="Snippet1"::: + ]]> The value supplied in the parameter is an invalid back-end data type. @@ -164,19 +164,19 @@ OleDbDataReader reader = command.ExecuteReader(); An object. Initializes a new instance of the class that uses the parameter name and an object. - in the `value` parameter, the is inferred from the Microsoft .NET Framework type of the . - - Use caution when you are using this overload of the constructor. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero, as the following Microsoft Visual C# example demonstrates. - -``` -Parameter = new OracleParameter("pname", Convert.ToInt32(0)); -``` - - If you do not perform this conversion, the compiler will assume that you are trying to call the `OracleParameter`(`string`, `OracleType`) constructor overload. - + in the `value` parameter, the is inferred from the Microsoft .NET Framework type of the . + + Use caution when you are using this overload of the constructor. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero, as the following Microsoft Visual C# example demonstrates. + +``` +Parameter = new OracleParameter("pname", Convert.ToInt32(0)); +``` + + If you do not perform this conversion, the compiler will assume that you are trying to call the `OracleParameter`(`string`, `OracleType`) constructor overload. + ]]> @@ -206,14 +206,14 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); The length of the parameter. Initializes a new instance of the class that uses the parameter name, data type, and length. - and sets some of its properties. - + and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter2/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter2/VB/source.vb" id="Snippet1"::: + ]]> The value supplied in the parameter is an invalid back-end data type. @@ -246,14 +246,14 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); The name of the source column. Initializes a new instance of the class that uses the parameter name, data type, length, and source column name. - and sets some of its properties. - + and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter3/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter3/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter3/VB/source.vb" id="Snippet1"::: + ]]> The value supplied in the parameter is an invalid back-end data type. @@ -337,14 +337,14 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); An that is the value of the . Initializes a new instance of the class that uses the parameter name, data type, length, source column name, parameter direction, numeric precision, and other properties. - and displays the . - + and displays the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter4/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.OracleParameter4/VB/source.vb" id="Snippet1"::: + ]]> The value supplied in the parameter is an invalid back-end data type. @@ -391,23 +391,23 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); Gets or sets the of the parameter. One of the values. The default is . - and are linked. Therefore, setting the changes the to a supporting . - - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . - - For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - - - -## Examples - The following example creates an and sets some of its properties. - + and are linked. Therefore, setting the changes the to a supporting . + + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . + + For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter.DbType/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.DbType/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter.DbType/VB/source.vb" id="Snippet1"::: + ]]> The property was not set to a valid . @@ -451,39 +451,39 @@ Parameter = new OracleParameter("pname", Convert.ToInt32(0)); Gets or sets a value that indicates 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. - - `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call on the . - - - -## Examples - The following example creates a and sets some of its properties. - -```vb -Public Sub CreateOracleDbParameter() - Dim parameter As New OracleParameter() - parameter.ParameterName = "pDName" - parameter.DbType = DbType.String - parameter.Value = "ENGINEERING" - parameter.SourceColumn = "DName" -End Sub -``` - -```csharp -public void CreateOracleDbParameter() -{ - OracleParameter parameter = new OracleParameter(); - parameter.ParameterName = "pDName"; - parameter.DbType = DbType.String; - parameter.Value = "ENGINEERING"; - parameter.SourceColumn = "DName"; -} -``` - + is output, and execution of the associated does not return a value, the contains a null value. + + `Output`, `InputOut`, and `ReturnValue` parameters returned by calling cannot be accessed until you call on the . + + + +## Examples + The following example creates a and sets some of its properties. + +```vb +Public Sub CreateOracleDbParameter() + Dim parameter As New OracleParameter() + parameter.ParameterName = "pDName" + parameter.DbType = DbType.String + parameter.Value = "ENGINEERING" + parameter.SourceColumn = "DName" +End Sub +``` + +```csharp +public void CreateOracleDbParameter() +{ + OracleParameter parameter = new OracleParameter(); + parameter.ParameterName = "pDName"; + parameter.DbType = DbType.String; + parameter.Value = "ENGINEERING"; + parameter.SourceColumn = "DName"; +} +``` + ]]> The property was not set to one of the valid values. @@ -532,33 +532,33 @@ public void CreateOracleDbParameter() if null values are accepted, otherwise . The default is . - class. - - - -## Examples - The following example creates a and sets some of its properties. - -```vb -Public Sub CreateOracleParameter() - Dim parameter As New OracleParameter("DName", OracleType.VarChar, 14) - parameter.IsNullable = True - parameter.Direction = ParameterDirection.Output -End Sub -``` - -```csharp -public void CreateOracleParameter() -{ - OracleParameter parameter = new OracleParameter("DName", OracleType.VarChar, 14); - parameter.IsNullable = true; - parameter.Direction = ParameterDirection.Output; -} -``` - + class. + + + +## Examples + The following example creates a and sets some of its properties. + +```vb +Public Sub CreateOracleParameter() + Dim parameter As New OracleParameter("DName", OracleType.VarChar, 14) + parameter.IsNullable = True + parameter.Direction = ParameterDirection.Output +End Sub +``` + +```csharp +public void CreateOracleParameter() +{ + OracleParameter parameter = new OracleParameter("DName", OracleType.VarChar, 14); + parameter.IsNullable = true; + parameter.Direction = ParameterDirection.Output; +} +``` + ]]> @@ -598,35 +598,35 @@ public void CreateOracleParameter() Gets or sets the offset to the property. The offset to the . The default is 0. - and sets some of its properties. - -```vb -Public Sub CreateOracleParameter() - Dim parameter As New OracleParameter("pDName", OracleType.VarChar) - parameter.IsNullable = True - parameter.Offset = 3 -End Sub -``` - -```csharp -public void CreateOracleParameter() -{ - OracleParameter parameter = new OracleParameter("pDName", OracleType.VarChar); - parameter.IsNullable = true; - parameter.Offset = 3; -} -``` - + and sets some of its properties. + +```vb +Public Sub CreateOracleParameter() + Dim parameter As New OracleParameter("pDName", OracleType.VarChar) + parameter.IsNullable = True + parameter.Offset = 3 +End Sub +``` + +```csharp +public void CreateOracleParameter() +{ + OracleParameter parameter = new OracleParameter("pDName", OracleType.VarChar); + parameter.IsNullable = true; + parameter.Offset = 3; +} +``` + ]]> @@ -666,15 +666,15 @@ public void CreateOracleParameter() Gets or sets the of the parameter. An value that is the of the parameter. The default is . - and are linked. Therefore, setting the changes the to a supporting . - - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . - - For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - + and are linked. Therefore, setting the changes the to a supporting . + + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. For `String` data types the default is . + + For a list of the supported data types, see the appropriate member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + ]]> @@ -712,37 +712,37 @@ public void CreateOracleParameter() Gets or sets the name of the . The name of the . The default is an empty string. - and sets some of its properties. - -```vb -Public Sub CreateOracleDbParameter() - Dim parameter As New OracleParameter() - parameter.ParameterName = "pDName" - parameter.DbType = DbType.String - parameter.Value = "ENGINEERING" - parameter.SourceColumn = "DName" -End Sub -``` - -```csharp -public void CreateOracleDbParameter() -{ - OracleParameter parameter = new OracleParameter(); - parameter.ParameterName = "pDName"; - parameter.DbType = DbType.String; - parameter.Value = "ENGINEERING"; - parameter.SourceColumn = "DName"; -} -``` - + and sets some of its properties. + +```vb +Public Sub CreateOracleDbParameter() + Dim parameter As New OracleParameter() + parameter.ParameterName = "pDName" + parameter.DbType = DbType.String + parameter.Value = "ENGINEERING" + parameter.SourceColumn = "DName" +End Sub +``` + +```csharp +public void CreateOracleDbParameter() +{ + OracleParameter parameter = new OracleParameter(); + parameter.ParameterName = "pDName"; + parameter.DbType = DbType.String; + parameter.Value = "ENGINEERING"; + parameter.SourceColumn = "DName"; +} +``` + ]]> @@ -789,11 +789,11 @@ public void CreateOracleDbParameter() Gets or sets the maximum number of digits used to represent the property. The maximum number of digits used to represent the property. The default value is 0, which indicates that the data provider sets the precision for . - or properties has no effect. - + or properties has no effect. + ]]> @@ -818,11 +818,11 @@ public void CreateOracleDbParameter() Resets the type associated with this . - and properties of the . - + and properties of the . + ]]> @@ -850,11 +850,11 @@ public void CreateOracleDbParameter() Resets the type associated with this . - and properties of the . - + and properties of the . + ]]> @@ -904,11 +904,11 @@ public void CreateOracleDbParameter() Gets or sets the number of decimal places to which is resolved. The number of decimal places to which is resolved. The default is 0. - or properties has no effect. - + or properties has no effect. + ]]> @@ -946,47 +946,47 @@ public void CreateOracleDbParameter() Gets or sets the maximum size, in bytes, of the data within the column. The maximum size, in bytes, of the data within the column. The default value is 0 (to be used when you do not want to specify the maximum size of the value). - 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. - - 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. - - For bidirectional and output parameters, and return values, you must set the value of Size. This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. - - The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. - - For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. - - - -## Examples - The following example creates a and sets some of its properties. - -```vb -Public Sub CreateOracleParameter() - Dim parameter As New OracleParameter("pDescription", OracleType.VarChar) - parameter.IsNullable = True - parameter.Direction = ParameterDirection.Output - parameter.Size = 88 -End Sub -``` - -```csharp -public void CreateOracleParameter() -{ - OracleParameter parameter = new OracleParameter("pDescription", OracleType.VarChar); - parameter.IsNullable = true; - parameter.Direction = ParameterDirection.Output; - parameter.Size = 88; -} -``` - + 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. + + 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. + + For bidirectional and output parameters, and return values, you must set the value of Size. This is not required for input parameters, and if not explicitly set, the value of is inferred from the actual size of the specified parameter when a parameterized statement is executed. + + The , , and properties of a parameter can be inferred by setting . Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, does not contain inferred value after statement execution. + + For fixed length data types, the value of is ignored. It can be retrieved for informational purposes, and returns the maximum amount of bytes the provider uses when transmitting the value of the parameter to the server. + + + +## Examples + The following example creates a and sets some of its properties. + +```vb +Public Sub CreateOracleParameter() + Dim parameter As New OracleParameter("pDescription", OracleType.VarChar) + parameter.IsNullable = True + parameter.Direction = ParameterDirection.Output + parameter.Size = 88 +End Sub +``` + +```csharp +public void CreateOracleParameter() +{ + OracleParameter parameter = new OracleParameter("pDescription", OracleType.VarChar); + parameter.IsNullable = true; + parameter.Direction = ParameterDirection.Output; + parameter.Size = 88; +} +``` + ]]> @@ -1024,37 +1024,37 @@ public void CreateOracleParameter() Gets or sets the name of the source column mapped to the and used for loading or returning the . The name of the source column 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 a and sets some of its properties. - -```vb -Public Sub CreateOracleDbParameter() - Dim parameter As New OracleParameter() - parameter.ParameterName = "pDName" - parameter.DbType = DbType.String - parameter.Value = "ENGINEERING" - parameter.SourceColumn = "DName" -End Sub -``` - -```csharp -public void CreateOracleDbParameter() -{ - OracleParameter parameter = new OracleParameter(); - parameter.ParameterName = "pDName"; - parameter.DbType = DbType.String; - parameter.Value = "ENGINEERING"; - parameter.SourceColumn = "DName"; -} -``` - + and the may be bidirectional depending on the value of the property. + + + +## Examples + The following example creates a and sets some of its properties. + +```vb +Public Sub CreateOracleDbParameter() + Dim parameter As New OracleParameter() + parameter.ParameterName = "pDName" + parameter.DbType = DbType.String + parameter.Value = "ENGINEERING" + parameter.SourceColumn = "DName" +End Sub +``` + +```csharp +public void CreateOracleDbParameter() +{ + OracleParameter parameter = new OracleParameter(); + parameter.ParameterName = "pDName"; + parameter.DbType = DbType.String; + parameter.Value = "ENGINEERING"; + parameter.SourceColumn = "DName"; +} +``` + ]]> @@ -1076,30 +1076,30 @@ public void CreateOracleDbParameter() System.Boolean - Gets or sets a value which indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. + Gets or sets a value that indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. if the source column is nullable; otherwise, . - is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . - - uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): - -``` -((@IsNull_FieldName = 1 AND FieldName IS NULL) OR - (FieldName = @Original_FieldName)) -``` - - If for the field is false, generates the following WHERE clause: - -``` -FieldName = @OriginalFieldName -``` - - In addition, @IsNull_FieldName contains 1 if the source field contains null, and 0 if it does not. This mechanism allows for a performance optimization in Oracle Server, and provides for common code that works across multiple providers. - + is used by the to correctly generate update commands when dealing with nullable columns. Generally, use of is limited to developers inheriting from . + + uses this property to determine whether the source column is nullable, and sets this property to `true` if it is nullable, and `false` if it is not. When is generating its Update statement, it examines the for each parameter. If the property is `true`, generates a WHERE clauses like the following (in this query expression, "FieldName" represents the name of the field): + +``` +((@IsNull_FieldName = 1 AND FieldName IS NULL) OR + (FieldName = @Original_FieldName)) +``` + + If for the field is false, generates the following WHERE clause: + +``` +FieldName = @OriginalFieldName +``` + + In addition, @IsNull_FieldName contains 1 if the source field contains null, and 0 if it does not. This mechanism allows for a performance optimization in Oracle Server, and provides for common code that works across multiple providers. + ]]> @@ -1137,37 +1137,37 @@ FieldName = @OriginalFieldName Gets or sets the to use when you load . One of the values. The default is . - 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. - - - -## Examples - The following example creates a and sets some of its properties. - -```vb -Public Sub CreateOracleParameter() - Dim parameter As New OracleParameter("pDName", OracleType.VarChar) - parameter.IsNullable = True - parameter.SourceColumn = "Description" - parameter.SourceVersion = DataRowVersion.Current - parameter.Direction = ParameterDirection.Output -End Sub -``` - -```csharp -public void CreateOracleParameter() -{ - OracleParameter parameter = new OracleParameter("pDName", OracleType.VarChar); - parameter.IsNullable = true; - parameter.SourceColumn = "Description"; - parameter.SourceVersion = DataRowVersion.Current; - parameter.Direction = ParameterDirection.Output; -} -``` - + 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. + + + +## Examples + The following example creates a and sets some of its properties. + +```vb +Public Sub CreateOracleParameter() + Dim parameter As New OracleParameter("pDName", OracleType.VarChar) + parameter.IsNullable = True + parameter.SourceColumn = "Description" + parameter.SourceVersion = DataRowVersion.Current + parameter.Direction = ParameterDirection.Output +End Sub +``` + +```csharp +public void CreateOracleParameter() +{ + OracleParameter parameter = new OracleParameter("pDName", OracleType.VarChar); + parameter.IsNullable = true; + parameter.SourceColumn = "Description"; + parameter.SourceVersion = DataRowVersion.Current; + parameter.Direction = ParameterDirection.Output; +} +``` + ]]> @@ -1197,11 +1197,11 @@ public void CreateOracleParameter() For a description of this member, see . A new object that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1271,23 +1271,23 @@ public void CreateOracleParameter() Gets or sets the value of the parameter. An object 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. - - For an input parameter, can be set to an object of either a Microsoft .NET Framework data type or an Oracle data type (for example, an or ). - - When you send a null parameter value to the server, you must specify DBNull, not null. A 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 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 , , and properties of a parameter can be inferred by setting Value. Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, Size does not contain inferred value after statement execution. - - 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. - + 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. + + For an input parameter, can be set to an object of either a Microsoft .NET Framework data type or an Oracle data type (for example, an or ). + + When you send a null parameter value to the server, you must specify DBNull, not null. A 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 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 , , and properties of a parameter can be inferred by setting Value. Therefore, you are not required to specify them. However, they are not exposed in property settings. For example, if the size of the parameter has been inferred, Size does not contain inferred value after statement execution. + + 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. + ]]> diff --git a/xml/System.Data.OracleClient/OracleParameterCollection.xml b/xml/System.Data.OracleClient/OracleParameterCollection.xml index a2aaa649743..cc6e5ff5ce9 100644 --- a/xml/System.Data.OracleClient/OracleParameterCollection.xml +++ b/xml/System.Data.OracleClient/OracleParameterCollection.xml @@ -55,27 +55,27 @@ Represents a collection of parameters relevant to an as well as their respective mappings to columns in a . This class cannot be inherited. - of `CommandType.Text`. In this case, named parameters must be used. For example: - -``` -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. - - - -## Examples - The following example creates multiple instances of through the within the . These parameters are used to select data within the database and then place the data in the . This example assumes that a and an have already been created with the appropriate schema, commands, and connection. - + of `CommandType.Text`. In this case, named parameters must be used. For example: + +``` +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. + + + +## Examples + The following example creates multiple instances of through the within the . These parameters are used to select data within the database and then place the data in the . This example assumes that a and an have already been created with the appropriate schema, commands, and connection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameter/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameter/VB/source.vb" id="Snippet1"::: + ]]> @@ -134,14 +134,14 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID Adds the specified to the . A reference to the new object. - , adds instances of to the collection, and returns a reference to the new . - + , adds instances of to the collection, and returns a reference to the new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/VB/source.vb" id="Snippet1"::: + ]]> The specified in the parameter is already added to this or another . @@ -217,14 +217,14 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID Adds an to the given the parameter name and data type. A reference to the new object. - , adds instances of to the collection, and returns a reference to the new . - + , adds instances of to the collection, and returns a reference to the new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add2/VB/source.vb" id="Snippet1"::: + ]]> @@ -267,17 +267,17 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID Adds an to the given the parameter name and value. A reference to the new object. - method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero, as the following C# example demonstrates. - -``` -parameters.Add("pname", Convert.ToInt32(0)); -``` - - If you do not perform this conversion, the compiler will assume you are attempting to call the `OracleParameterCollection.Add` (`string`, `OracleType`) overload. - + method to specify integer parameter values. Because this overload takes a `value` of type , you must convert the integral value to an type when the value is zero, as the following C# example demonstrates. + +``` +parameters.Add("pname", Convert.ToInt32(0)); +``` + + If you do not perform this conversion, the compiler will assume you are attempting to call the `OracleParameterCollection.Add` (`string`, `OracleType`) overload. + ]]> The parameter is not an . @@ -313,14 +313,14 @@ parameters.Add("pname", Convert.ToInt32(0)); Adds an to the given the parameter name, data type, and column length. A reference to the new object. - , adds an instance of to the collection, and returns a reference to the new . - + , adds an instance of to the collection, and returns a reference to the new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add3/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add3/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add3/VB/source.vb" id="Snippet1"::: + ]]> @@ -357,14 +357,14 @@ parameters.Add("pname", Convert.ToInt32(0)); Adds an to the given the parameter name, data type, column length, and source column name. A reference to the new object. - , adds an instance of to the collection, and returns a reference to the new . - + , adds an instance of to the collection, and returns a reference to the new . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add4/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Add4/VB/source.vb" id="Snippet1"::: + ]]> @@ -726,11 +726,11 @@ parameters.Add("pname", Convert.ToInt32(0)); Returns an enumerator that iterates through the . An that can be used to iterate through the collection. - method which supports a simple iteration over a collection by a .NET Framework data provider. - + method, which supports a simple iteration over a collection by a .NET data provider. + ]]> @@ -1085,14 +1085,14 @@ parameters.Add("pname", Convert.ToInt32(0)); Gets or sets the at the specified index. The at the specified index. - , adds instances of to the collection, displays the names of its objects, and then clears the collection. - + , adds instances of to the collection, displays the names of its objects, and then clears the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Count/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Count/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.Count/VB/source.vb" id="Snippet1"::: + ]]> The index specified does not exist. @@ -1123,14 +1123,14 @@ parameters.Add("pname", Convert.ToInt32(0)); Gets or sets the with the specified name. The with the specified name. - with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. - + with a given within an . If the parameter exists, the example displays the name and index of the parameter. If the parameter does not exist, the example displays an error. This example assumes that an has already been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.this1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.this1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleParameterCollection.this1/VB/source.vb" id="Snippet1"::: + ]]> The name specified does not exist. diff --git a/xml/System.Data.Services.Client/DataServiceContext.xml b/xml/System.Data.Services.Client/DataServiceContext.xml index 30215258696..9168c92fa62 100644 --- a/xml/System.Data.Services.Client/DataServiceContext.xml +++ b/xml/System.Data.Services.Client/DataServiceContext.xml @@ -1280,7 +1280,7 @@ The result from the operation that contains the binary data stream. Called to complete the asynchronous operation of retrieving a binary property as a stream. - An instance of which contains the response stream along with its metadata. + An instance of that contains the response stream along with its metadata. System.Data.Services.Internal.ProjectedWrapperMany - Gets or sets another instance of which contains the set of the next eight projected properties, and possibly another link. + Gets or sets another instance of that contains the set of the next eight projected properties and possibly another link. The next set of properties. To be added. diff --git a/xml/System.Data.SqlClient/SqlCommand.xml b/xml/System.Data.SqlClient/SqlCommand.xml index 40287ce045e..7c196f387f5 100644 --- a/xml/System.Data.SqlClient/SqlCommand.xml +++ b/xml/System.Data.SqlClient/SqlCommand.xml @@ -90,8 +90,8 @@ |Item|Description| |----------|-----------------| -||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , generally executing commands such as INSERT, DELETE, UPDATE, and SET statements. Each call to must be paired with a call to which finishes the operation, typically on a separate thread.| -||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more results sets from the server. Each call to must be paired with a call to which finishes the operation, typically on a separate thread.| +||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , generally executing commands such as INSERT, DELETE, UPDATE, and SET statements. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| +||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more results sets from the server. Each call to must be paired with a call to , which finishes the operation, typically on a separate thread.| ||Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this . Each call to `BeginExecuteXmlReader` must be paired with a call to `EndExecuteXmlReader`, which finishes the operation, typically on a separate thread, and returns an object.| ||Executes commands that return rows. For increased performance, invokes commands using the Transact-SQL `sp_executesql` system stored procedure. Therefore, might not have the effect that you want if used to execute commands such as Transact-SQL SET statements.| ||Executes commands such as Transact-SQL INSERT, DELETE, UPDATE, and SET statements.| @@ -1075,7 +1075,7 @@ A timeout occurred during a streaming operation. For more information about stre An delegate that is invoked when the command's execution has completed. Pass ( in Microsoft Visual Basic) to indicate that no callback is required. A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the property. Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more result sets from the server, given a callback procedure and state information. - An that can be used to poll, wait for results, or both; this value is also needed when invoking , which returns a instance which can be used to retrieve the returned rows. + An that can be used to poll, wait for results, or both; this value is also needed when invoking , which returns a instance that can be used to retrieve the returned rows. other than **Xml A user-defined state object that is passed to the callback procedure. Retrieve this object from within the callback procedure using the property. One of the values, indicating options for statement execution and data retrieval. Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , using one of the values, and retrieving one or more result sets from the server, given a callback procedure and state information. - An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns a instance which can be used to retrieve the returned rows. + An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns a instance that can be used to retrieve the returned rows. System.Boolean - Gets or sets a value which indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. + Gets or sets a value that indicates whether the source column is nullable. This allows to correctly generate Update statements for nullable columns. if the source column is nullable; if it is not. diff --git a/xml/System.Data.SqlTypes/SqlDecimal.xml b/xml/System.Data.SqlTypes/SqlDecimal.xml index ddd5f31b69d..0d88697d789 100644 --- a/xml/System.Data.SqlTypes/SqlDecimal.xml +++ b/xml/System.Data.SqlTypes/SqlDecimal.xml @@ -88,11 +88,11 @@ Represents a numeric value between - 10^38 +1 and 10^38 - 1, with fixed precision and scale. - has different underlying data structures from its corresponding .NET Framework data type. has no concept of precision. It uses 3 DWORDs (12 bytes) to store the actual data, and therefore has a maximum scale of 28. The data range is -79,228,162,514,264,337,593,543,950,335 through 79,228,162,514,264,337,593,543,950,335. has both precision and scale. It uses 4 unsigned 4-byte integers to store the actual data, and therefore has maximum precision and scale of 38. The data range is - 10^38 +1 through 10^38 - 1. - + has different underlying data structures from its corresponding .NET Framework data type. has no concept of precision. It uses 3 DWORDs (12 bytes) to store the actual data, and therefore has a maximum scale of 28. The data range is -79,228,162,514,264,337,593,543,950,335 through 79,228,162,514,264,337,593,543,950,335. has both precision and scale. It uses 4 unsigned 4-byte integers to store the actual data, and therefore has maximum precision and scale of 38. The data range is - 10^38 +1 through 10^38 - 1. + ]]> SQL Server Data Types and ADO.NET @@ -239,7 +239,7 @@ - The supplied integer value which will the used as the value of the new structure. + The value to use as the value of the new structure. Initializes a new instance of the structure using the supplied integer value. To be added. SQL Server Data Types and ADO.NET @@ -285,7 +285,7 @@ - The supplied long integer value which will the used as the value of the new structure. + The value to use as the value of the new structure. Initializes a new instance of the structure using the supplied long integer value. To be added. SQL Server Data Types and ADO.NET @@ -707,28 +707,28 @@ The to be compared. Compares this instance to the supplied object and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -783,28 +783,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -1418,11 +1418,11 @@ if this structure is null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1621,11 +1621,11 @@ A constant representing the largest possible value for the property. - SQL Server Data Types and ADO.NET @@ -1718,11 +1718,11 @@ A constant representing the maximum value of a structure. - SQL Server Data Types and ADO.NET @@ -1770,11 +1770,11 @@ A constant representing the minimum value for a structure. - SQL Server Data Types and ADO.NET @@ -1926,11 +1926,11 @@ Represents a that can be assigned to this instance of the class. - SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlFileStream.xml b/xml/System.Data.SqlTypes/SqlFileStream.xml index a9873faaabb..6065bcc3caf 100644 --- a/xml/System.Data.SqlTypes/SqlFileStream.xml +++ b/xml/System.Data.SqlTypes/SqlFileStream.xml @@ -111,7 +111,7 @@ When using , points to a zero byte file. Existing data will be overwritten when the object is closed and the transaction is committed. - When using , the points to a file which has all the existing data in it. The handle is positioned at the beginning of the file. You can use one of the methods to move the handle position within the file to write or append new data. + When using , the points to a file that has all the existing data in it. The handle is positioned at the beginning of the file. You can use one of the methods to move the handle position within the file to write or append new data. Initializes a new instance of the class. , points to a zero byte file. Existing data will be overwritten when the object is closed and the transaction is committed. - When using , the points to a file which has all the existing data in it. The handle is positioned at the beginning of the file. You can use one of the methods to move the handle position within the file to write or append new data. + When using , the points to a file that has all the existing data in it. The handle is positioned at the beginning of the file. You can use one of the methods to move the handle position within the file to write or append new data. Specifies the option to use while opening the file. Supported values are , , , and . The allocation size to use while creating a file. If set to 0, the default value is used. Initializes a new instance of the class. diff --git a/xml/System.Data.SqlTypes/SqlSingle.xml b/xml/System.Data.SqlTypes/SqlSingle.xml index 901a986af5c..6203b8b6f99 100644 --- a/xml/System.Data.SqlTypes/SqlSingle.xml +++ b/xml/System.Data.SqlTypes/SqlSingle.xml @@ -84,11 +84,11 @@ Represents a floating point number within the range of -3.40E +38 through 3.40E +38 to be stored in or retrieved from a database. - . - + ]]> SQL Server Data Types and ADO.NET @@ -144,7 +144,7 @@ - A double value which will be used as the of the new structure. + A double value that will be used as the of the new structure. Initializes a new instance of the structure using the supplied double parameter. To be added. SQL Server Data Types and ADO.NET @@ -302,28 +302,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return Value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return Value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -378,28 +378,28 @@ The to be compared. Compares this instance to the supplied and returns an indication of their relative values. - A signed number that indicates the relative values of the instance and the object. - - Return value - - Condition - - Less than zero - - This instance is less than the object. - - Zero - - This instance is the same as the object. - - Greater than zero - - This instance is greater than the object - - -or- - - The object is a null reference ( in Visual Basic) - + A signed number that indicates the relative values of the instance and the object. + + Return value + + Condition + + Less than zero + + This instance is less than the object. + + Zero + + This instance is the same as the object. + + Greater than zero + + This instance is greater than the object + + -or- + + The object is a null reference ( in Visual Basic) + To be added. SQL Server Data Types and ADO.NET @@ -863,11 +863,11 @@ if null. Otherwise, . - SQL Server Data Types and ADO.NET @@ -1020,11 +1020,11 @@ Represents the maximum value that can be assigned to the property of an instance of the class. - SQL Server Data Types and ADO.NET @@ -1072,11 +1072,11 @@ Represents the minimum value that can be assigned to property of an instance of the class. - SQL Server Data Types and ADO.NET @@ -1228,11 +1228,11 @@ Represents a that can be assigned to this instance of the structure. - SQL Server Data Types and ADO.NET @@ -3234,11 +3234,11 @@ This member is an explicit interface member implementation. It can be used only Represents the zero value that can be assigned to the property of an instance of the class. - class. - + class. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data/DataRow.xml b/xml/System.Data/DataRow.xml index 77325d68c3c..e01b3b13951 100644 --- a/xml/System.Data/DataRow.xml +++ b/xml/System.Data/DataRow.xml @@ -178,9 +178,7 @@ See the method for more information. - The class also has an method which affects changes made to the whole table. For more information and a code example that demonstrates how to accept and reject changes to individual data rows, see [AcceptChanges and RejectChanges](/dotnet/framework/data/adonet/dataset-datatable-dataview/acceptchanges-and-rejectchanges). - - + The class also has an method, which affects changes made to the whole table. For more information and a code example that demonstrates how to accept and reject changes to individual data rows, see [AcceptChanges and RejectChanges](/dotnet/framework/data/adonet/dataset-datatable-dataview/acceptchanges-and-rejectchanges). ## Examples The following example first creates a new with one column, and then creates a single . As the is created, added, modified, and deleted, its is printed. diff --git a/xml/System.Data/DataSet.xml b/xml/System.Data/DataSet.xml index d6b88241f14..328e7015d21 100644 --- a/xml/System.Data/DataSet.xml +++ b/xml/System.Data/DataSet.xml @@ -5046,7 +5046,7 @@ class Program { > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method which is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . Classes that derive from the class include , , , and . @@ -5129,7 +5129,7 @@ class Program { > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method which is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . Classes that inherit from the class include the and classes. @@ -5211,7 +5211,7 @@ class Program { > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method which is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . > [!NOTE] > If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. @@ -5292,7 +5292,7 @@ class Program { > [!NOTE] > Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The method is generally invoked before invoking the method which is used to fill the . + The method is generally invoked before invoking the method that is used to fill the . The class is abstract. A class that inherits from the `XmlReader` is the class. diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index 8b04cf72562..341a28016fc 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -658,9 +658,7 @@ The following example creates two objects and one < defines the relationship between two tables. Typically, two tables are linked through a single field that contains the same data. For example, a table which 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 which 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. - - + 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. @@ -5245,7 +5243,7 @@ public class A { The XML schema is interpreted according to the XSD standard. - The `ReadXmlSchema` method is generally invoked before invoking the method which is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . ]]> @@ -5316,7 +5314,7 @@ public class A { Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method which is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . To create a nested relation using XML schema, use implicit nested elements. You can also configure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5397,7 +5395,7 @@ public class A { Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method which is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . To create a nested relation using XML schema, use implicit nested elements. You can also reconfigure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5477,7 +5475,7 @@ public class A { Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method which is used to fill the `DataTable`. + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the `DataTable`. To create a nested relation using XML schema, use implicit nested elements. You can also reconfigure the nested relation to use explicit column names. Elements must be implicitly nested in order for the corresponding DataTables to participate in a nested relation. @@ -5558,7 +5556,7 @@ public class A { Data corruption can occur if the msdata:DataType and the xs:type types do not match. No exception will be thrown. - The `ReadXmlSchema` method is generally invoked before invoking the method which is used to fill the . + The `ReadXmlSchema` method is generally invoked before invoking the method that is used to fill the . > [!NOTE] > The way to create a nested relation using XML schema is to have implicit nested elements. Additionally, the nested relation could be re-wired, to use explicit column names. It is mandatory for elements to be implicitly nested for the corresponding DataTables to participate in a nested relation. diff --git a/xml/System.Data/IDataRecord.xml b/xml/System.Data/IDataRecord.xml index eb368b1f6c4..fbb25fa286f 100644 --- a/xml/System.Data/IDataRecord.xml +++ b/xml/System.Data/IDataRecord.xml @@ -43,62 +43,62 @@ Provides access to the column values within each row for a , and is implemented by .NET data providers that access relational databases. - and interfaces enable an inheriting class to implement a `DataReader` class. This provides a way 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 . Typically, you do this by obtaining a `DataReader` through the `ExecuteReader` method of the `Command` object. - - Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. - - Providers implementing a `DataReader` are required to expose data in common language runtime (CLR) types. Type coercion is defined for some types not included in the CLR. These values may be accessed as alternative types that comply with CLR types. As an example, the following table lists suggested mappings from OLE DB data types to CLR types, with alternative types in parentheses. - -|OLE DB type|CLR type| -|-----------------|--------------| -|DBTYPE_BOOL|Int16| -|DBTYPE_BSTR|string| -|DBTYPE_BYTES|byte[]| -|DBTYPE_CY|Decimal| -|DBTYPE_DATE|DateTime| -|DBTYPE_DBDATE|DateTime| -|DBTYPE_DBTIME|DateTime| -|DBTYPE_DBTIMESTAMP|DateTime| -|DBTYPE_DECIMAL|Decimal| -|DBTYPE_EMPTY|null| -|DBTYPE_ERROR|ExternalException| -|DBTYPE_FILETIME|DateTime| -|DBTYPE_GUID|Guid| -|DBTYPE_HCHAPTER|not supported| -|DBTYPE_I1|SByte| -|DBTYPE_I2|Int16| -|DBTYPE_I4|Int32| -|DBTYPE_I8|Int64| -|DBTYPE_IDISPATCH|object| -|DBTYPE_IUNKNOWN|object| -|DBTYPE_NULL|DBNull.Value| -|DBTYPE_NUMERIC|Decimal| -|DBTYPE_PROPVARIANT|object| -|DBTYPE_R4|Single| -|DBTYPE_R8|Double| -|DBTYPE_STR|string| -|DBTYPE_UDT|not supported| -|DBTYPE_UI1|byte (Int16)| -|DBTYPE_UI2|UInt16 (Int32)| -|DBTYPE_UI4|UInt32 (Int64)| -|DBTYPE_UI8|UInt64 (Decimal)| -|DBTYPE_VARIANT|object| -|DBTYPE_VARNUMERIC|not supported| -|DBTYPE_WSTR|string| - - - -## 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 , and then the . - + and interfaces enable an inheriting class to implement a `DataReader` class. This provides a way 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 . Typically, you do this by obtaining a `DataReader` through the `ExecuteReader` method of the `Command` object. + + Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. + + Providers implementing a `DataReader` are required to expose data in common language runtime (CLR) types. Type coercion is defined for some types not included in the CLR. These values may be accessed as alternative types that comply with CLR types. As an example, the following table lists suggested mappings from OLE DB data types to CLR types, with alternative types in parentheses. + +|OLE DB type|CLR type| +|-----------------|--------------| +|DBTYPE_BOOL|Int16| +|DBTYPE_BSTR|string| +|DBTYPE_BYTES|byte[]| +|DBTYPE_CY|Decimal| +|DBTYPE_DATE|DateTime| +|DBTYPE_DBDATE|DateTime| +|DBTYPE_DBTIME|DateTime| +|DBTYPE_DBTIMESTAMP|DateTime| +|DBTYPE_DECIMAL|Decimal| +|DBTYPE_EMPTY|null| +|DBTYPE_ERROR|ExternalException| +|DBTYPE_FILETIME|DateTime| +|DBTYPE_GUID|Guid| +|DBTYPE_HCHAPTER|not supported| +|DBTYPE_I1|SByte| +|DBTYPE_I2|Int16| +|DBTYPE_I4|Int32| +|DBTYPE_I8|Int64| +|DBTYPE_IDISPATCH|object| +|DBTYPE_IUNKNOWN|object| +|DBTYPE_NULL|DBNull.Value| +|DBTYPE_NUMERIC|Decimal| +|DBTYPE_PROPVARIANT|object| +|DBTYPE_R4|Single| +|DBTYPE_R8|Double| +|DBTYPE_STR|string| +|DBTYPE_UDT|not supported| +|DBTYPE_UI1|byte (Int16)| +|DBTYPE_UI2|UInt16 (Int32)| +|DBTYPE_UI4|UInt32 (Int64)| +|DBTYPE_UI8|UInt64 (Decimal)| +|DBTYPE_VARIANT|object| +|DBTYPE_VARNUMERIC|not supported| +|DBTYPE_WSTR|string| + + + +## 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 , and 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/VS_Snippets_ADO.NET/Classic WebData SqlDataReader.Read Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataReader.Read Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -143,11 +143,11 @@ Gets the number of columns in the current row. When not positioned in a valid recordset, 0; otherwise, the number of columns in the current record. The default is -1. - method), returns -1. - + method), returns -1. + ]]> @@ -196,11 +196,11 @@ Gets the value of the specified column as a Boolean. The value of the column. - The index passed was outside the range of 0 through . @@ -306,15 +306,15 @@ 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. Frequently 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. - - If you pass a buffer that is `null`, returns the length of the row in bytes. - - No conversions are performed; therefore the data retrieved must already be a byte array. - + returns the number of available bytes in the field. Frequently 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. + + If you pass a buffer that is `null`, returns the length of the row in bytes. + + No conversions are performed; therefore the data retrieved must already be a byte array. + ]]> The index passed was outside the range of 0 through . @@ -420,15 +420,15 @@ 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. Frequently this is the exact length of the field. However, the number returned may be less than the exact length of the field if `GetChars` has already been used to obtain characters from the field. - - If you pass a buffer that is `null`, `GetChars` returns the length of the field in characters. - - No conversions are performed; therefore the data retrieved must already be a character array. - + returns the number of available characters in the field. Frequently this is the exact length of the field. However, the number returned may be less than the exact length of the field if `GetChars` has already been used to obtain characters from the field. + + If you pass a buffer that is `null`, `GetChars` returns the length of the field in characters. + + No conversions are performed; therefore the data retrieved must already be a character array. + ]]> The index passed was outside the range of 0 through . @@ -525,11 +525,11 @@ Gets the data type information for the specified field. The data type information for the specified field. - The index passed was outside the range of 0 through . @@ -726,11 +726,11 @@ Gets the information corresponding to the type of that would be returned from . The information corresponding to the type of that would be returned from . - The index passed was outside the range of 0 through . @@ -1062,21 +1062,21 @@ Return the index of the named field. The index of the named field. - method. - + 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/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader.GetOrdinal/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader.GetOrdinal/VB/source.vb" id="Snippet1"::: + ]]> @@ -1169,8 +1169,8 @@ The index of the field to find. - Return the value of the specified field. - The which will contain the field value upon return. + Returns the value of the specified field. + The field value. To be added. The index passed was outside the range of 0 through . @@ -1219,13 +1219,13 @@ Populates an array of objects with the column values of the current record. 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. - + 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. + ]]> @@ -1275,11 +1275,11 @@ if the specified field is set to null; otherwise, . - , , and so on) to avoid raising an error. - + , , and so on) to avoid raising an error. + ]]> The index passed was outside the range of 0 through . @@ -1386,13 +1386,13 @@ Gets the column with the specified name. The column with the specified name as an . - No column with the specified name was found. diff --git a/xml/System.Device.Location/GeoCoordinateWatcher.xml b/xml/System.Device.Location/GeoCoordinateWatcher.xml index 72a87258448..e41e0348f74 100644 --- a/xml/System.Device.Location/GeoCoordinateWatcher.xml +++ b/xml/System.Device.Location/GeoCoordinateWatcher.xml @@ -32,43 +32,43 @@ Supplies location data that is based on latitude and longitude coordinates. - class supplies coordinate-based location data from the current location provider. The current location provider is prioritized as the highest on the computer, based on a number of factors, such as the age and accuracy of the data from all providers, the accuracy requested by location applications, and the power consumption and performance impact associated with the location provider. The current location provider might change over time, for instance, when a GPS device loses its satellite signal indoors and a Wi-Fi triangulation provider becomes the most accurate provider on the computer. - - 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 , , and properties support , so that an application can data-bind to these properties. - - In Windows 7, all the classes are fully functional if a location provider is installed and able to resolve the computer's location. - + class supplies coordinate-based location data from the current location provider. The current location provider is prioritized as the highest on the computer, based on a number of factors, such as the age and accuracy of the data from all providers, the accuracy requested by location applications, and the power consumption and performance impact associated with the location provider. The current location provider might change over time, for instance, when a GPS device loses its satellite signal indoors and a Wi-Fi triangulation provider becomes the most accurate provider on the computer. + + 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 , , and properties support , so that an application can data-bind to these properties. + + In Windows 7, all the classes are fully functional if a location provider is installed and able to resolve the computer's location. + > [!NOTE] -> On Windows 7 Starter Edition, the only supported location provider is the Default Location Provider in Control Panel, and an add-in must be installed to specify latitude and longitude. - - **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 . - -- The location indicated by the property of will always be . - -- No location events will be raised. - - - -## Examples - The following program shows how to create a and start acquiring data by using an initialization timeout. The code then prints the coordinates of the location, if known. - +> On Windows 7 Starter Edition, the only supported location provider is the Default Location Provider in Control Panel, and an add-in must be installed to specify latitude and longitude. + + **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 . + +- The location indicated by the property of will always be . + +- No location events will be raised. + + + +## Examples + The following program shows how to create a and start acquiring data by using an initialization timeout. The code then prints the coordinates of the location, if known. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdatasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet1"::: - - The following program shows how to receive continuous location updates by subscribing to events. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet1"::: + + The following program shows how to receive continuous location updates by subscribing to events. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdataasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataasync/vb/GetLocationDataAsync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataasync/vb/GetLocationDataAsync.vb" id="Snippet1"::: + ]]> @@ -81,17 +81,17 @@ Initializes a new instance of . - 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 . - -- No location events will be raised. - + 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 . + +- No location events will be raised. + ]]> @@ -117,19 +117,19 @@ Initializes a new instance of with default accuracy settings. - . - - **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 . - -- The location indicated by the property of will always be . - -- No location events will be raised. - + . + + **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 . + +- The location indicated by the property of will always be . + +- No location events will be raised. + ]]> @@ -151,22 +151,22 @@ - that indicates the requested accuracy level of the location provider. - + that indicates the requested accuracy level of the location provider. + An accuracy of can degrade performance and should be specified only when high accuracy is needed. Initializes a new instance of , given an accuracy level. - 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 . - -- No location events will be raised. - + 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 . + +- No location events will be raised. + ]]> @@ -187,23 +187,14 @@ System.Device.Location.GeoPositionAccuracy - The requested accuracy level for the location data that is provided by the . - - , which indicates the requested accuracy level of the location provider. + Gets the requested accuracy level for the location data that's provided by the . + The requested accuracy level of the location provider. - can degrade performance and should be specified only when high accuracy is needed. - - **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 . - -- The location indicated by the property of will always be . - -- No location events will be raised. - + can degrade performance and should be specified only when high accuracy is needed. + ]]> @@ -216,15 +207,15 @@ Releases all resources that are used by the current instance of the class. - when you are finished using the class. - - This method should be called so that unmanaged resources can be freed. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + when you are finished using the class. + + This method should be called so that unmanaged resources can be freed. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> @@ -257,15 +248,15 @@ Releases all resources that are used by the current instance of the class. - when you are finished using the class. - - This method should be called so that unmanaged resources can be freed. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + when you are finished using the class. + + This method should be called so that unmanaged resources can be freed. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> @@ -293,15 +284,15 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases all resources used by the current instance of the class. - when you are finished using the class. - - This method should be called so that unmanaged resources can be freed. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + when you are finished using the class. + + This method should be called so that unmanaged resources can be freed. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + ]]> @@ -352,26 +343,26 @@ The distance that must be moved, in meters, relative to the coordinate from the last event, before the location provider raises another event. Distance, in meters. - event and an update in the property. - + 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 . - -- The location indicated by the property of will always be . - -- No location events will be raised. - - The following diagram represents location coordinates that the location provider (for example, a GPS device) supplies to the computer. P1, in the diagram, represents the location data included in a event, and P2, P3, and P4 represent points within the movement threshold. So when the location provider supplies data indicating a location at those points (P1, P2, P3, and P4), no events are raised, and returns P1. The point P5 is outside of the distance, so at that point, is updated and a event is raised. - - ![Diagram illustrating MovementThreshold](~/add/media/ndp-movementthreshold.png "Diagram illustrating MovementThreshold") - +> 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 . + +- The location indicated by the property of will always be . + +- No location events will be raised. + + The following diagram represents location coordinates that the location provider (for example, a GPS device) supplies to the computer. P1, in the diagram, represents the location data included in a event, and P2, P3, and P4 represent points within the movement threshold. So when the location provider supplies data indicating a location at those points (P1, P2, P3, and P4), no events are raised, and returns P1. The point P5 is outside of the distance, so at that point, is updated and a event is raised. + + ![Diagram illustrating MovementThreshold](~/add/media/ndp-movementthreshold.png "Diagram illustrating MovementThreshold") + ]]> @@ -398,14 +389,14 @@ A object that contains the new location. Called when a event occurs. - events. - + events. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdataasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataasync/vb/GetLocationDataAsync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataasync/vb/GetLocationDataAsync.vb" id="Snippet1"::: + ]]> @@ -456,13 +447,13 @@ The name of the property that has changed. Called when a property of the changes. - event to implement data binding in Windows Forms applications. - - This method indicates that the property, the property, or the property has changed. - + event to implement data binding in Windows Forms applications. + + This method indicates that the property, the property, or the property has changed. + ]]> @@ -515,17 +506,17 @@ System.Device.Location.GeoPosition<System.Device.Location.GeoCoordinate> - Gets the which indicates the current location. - The which indicates the current location. + Gets the that indicates the current location. + The that indicates the current location. - property of the property is saved in a object. The latitude and longitude fields of the are printed if they are known. - + 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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet2"::: + ]]> @@ -552,21 +543,21 @@ Indicates that the latitude or longitude of the location data has changed. - . - - The object passed to the event handler includes the object that contains the updated location data. - - - -## Examples - The following example shows how to handle the first event. - + . + + The object passed to the event handler includes the object that contains the updated location data. + + + +## Examples + The following example shows how to handle the first event. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinate/Latitude/locationevent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.locationevent1/vb/locationevent.vb" id="Snippet1"::: + ]]> @@ -609,27 +600,27 @@ Initiate the acquisition of data from the current location provider. This method enables events and allows access to the property. - 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 current prioritized location provider does have data, it will be available synchronously immediately, and will be delivered asynchronously if events are being handled. - - If the calling application does not have permissions to access data from a location provider, the user will be prompted with a dialog box to either grant or deny permission. The dialog box will be modeless. - - - -## Examples - The following program handles the first location update that occurs after is called. - + 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 current prioritized location provider does have data, it will be available synchronously immediately, and will be delivered asynchronously if events are being handled. + + If the calling application does not have permissions to access data from a location provider, the user will be prompted with a dialog box to either grant or deny permission. The dialog box will be modeless. + + + +## Examples + The following program handles the first location update that occurs after is called. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Start/getlocationdataupdateonce.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataupdateonce/vb/GetLocationDataUpdateOnce.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdataupdateonce/vb/GetLocationDataUpdateOnce.vb" id="Snippet1"::: + ]]> @@ -694,16 +685,16 @@ Gets the current status of the . - A which indicates the availability of data from the . + A that indicates the availability of data from the . - events and prints a message based on the . - + events and prints a message based on the . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Status/showstatusupdates.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.showstatusupdates/vb/ShowStatusUpdates.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.showstatusupdates/vb/ShowStatusUpdates.vb" id="Snippet1"::: + ]]> @@ -731,19 +722,19 @@ Indicates that the status of the object has changed. - event is raised on the same thread that the object was created on. - - - -## Examples - The following example demonstrates how to handle events. - + event is raised on the same thread that the object was created on. + + + +## Examples + The following example demonstrates how to handle events. + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Status/showstatusupdates.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.showstatusupdates/vb/ShowStatusUpdates.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.showstatusupdates/vb/ShowStatusUpdates.vb" id="Snippet1"::: + ]]> @@ -776,13 +767,13 @@ Stops the from providing location data and events. - is called, no further events occur, and the property will return . - - When is called, the property is set to . - + is called, no further events occur, and the property will return . + + When is called, the property is set to . + ]]> @@ -927,19 +918,19 @@ This member is an explicit interface member implementation. It can be used only if data acquisition is started within the time period specified by ; otherwise, . - from the user interface thread of your application. - - - -## Examples - The following example demonstrates how to call . - + from the user interface thread of your application. + + + +## Examples + The following example demonstrates how to call . + :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdatasync.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Speech.Recognition/RecognizerInfo.xml b/xml/System.Speech.Recognition/RecognizerInfo.xml index e50f08ea39a..c1b3c3e55d2 100644 --- a/xml/System.Speech.Recognition/RecognizerInfo.xml +++ b/xml/System.Speech.Recognition/RecognizerInfo.xml @@ -31,42 +31,42 @@ Represents information about a or instance. - for a object or for a object. - - The information returned in instances of obtained from a is determined by the settings in the **Speech Properties** member of the **Control Panel**. - - You can use instances of to construct a specific configuration of using the constructor. - - The static method returns a list of all available configurations as instances. - - - -## Examples - The following example validates a given and identifier string against the permitted configurations, expressed as a list of objects. - - If the and identifier string are valid, the example creates a new instance of using the instance as an argument. - -```csharp - -private SpeechRecognitionEngine SelectRecognizer(CultureInfo requiredCulture, string requiredId) -{ - // Select based on a specific recognizer configuration - SpeechRecognitionEngine speechRecognitionEngine=null; - foreach (RecognizerInfo config in SpeechRecognitionEngine.InstalledRecognizers()) - { - if (config.Culture.Equals(requiredCulture) && config.Id== requiredId) - { - speechRecognitionEngine = new SpeechRecognitionEngine(config); - break; - } - } - return speechRecognitionEngine; -} -``` - + for a object or for a object. + + The information returned in instances of obtained from a is determined by the settings in the **Speech Properties** member of the **Control Panel**. + + You can use instances of to construct a specific configuration of using the constructor. + + The static method returns a list of all available configurations as instances. + + + +## Examples + The following example validates a given and identifier string against the permitted configurations, expressed as a list of objects. + + If the and identifier string are valid, the example creates a new instance of using the instance as an argument. + +```csharp + +private SpeechRecognitionEngine SelectRecognizer(CultureInfo requiredCulture, string requiredId) +{ + // Select based on a specific recognizer configuration + SpeechRecognitionEngine speechRecognitionEngine=null; + foreach (RecognizerInfo config in SpeechRecognitionEngine.InstalledRecognizers()) + { + if (config.Culture.Equals(requiredCulture) && config.Id== requiredId) + { + speechRecognitionEngine = new SpeechRecognitionEngine(config); + break; + } + } + return speechRecognitionEngine; +} +``` + ]]> @@ -100,43 +100,43 @@ private SpeechRecognitionEngine SelectRecognizer(CultureInfo requiredCulture, st Gets additional information about a or instance. Returns an instance of containing information about the configuration of a or object. - object in a . - - The key/value pairs contained in the instance returned by are concatenated into a text table. - -```csharp -private void recognizerInfoButton_Click(object sender, EventArgs e) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 } \n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - " {2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + object in a . + + The key/value pairs contained in the instance returned by are concatenated into a text table. + +```csharp +private void recognizerInfoButton_Click(object sender, EventArgs e) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 } \n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + " {2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> @@ -172,46 +172,46 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) Gets the culture supported by a or instance. Returns information about the culture supported by a given or instance. - object can include the name of the culture, the associated language, the country/region, the calendar used, and how to format dates and sort strings. - - - -## 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. - -```csharp -private void recognizerInfoButton_Click(object sender, EventArgs e) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 }\n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - "{2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + object can include the name of the culture, the associated language, the country/region, the calendar used, and how to format dates and sort strings. + + + +## 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. + +```csharp +private void recognizerInfoButton_Click(object sender, EventArgs e) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 }\n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + "{2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> @@ -247,41 +247,41 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) Gets the description of a or instance. Returns a that describes the configuration for a specific or instance. - 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) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 }\n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - "{2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + 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) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 }\n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + "{2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> @@ -342,46 +342,46 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) Gets the identifier of a or instance. Returns the identifier for a specific or instance. - 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 . - -``` -private void recognizerInfoButton_Click(object sender, EventArgs e) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 }\n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - "{2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + 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 . + +``` +private void recognizerInfoButton_Click(object sender, EventArgs e) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 }\n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + "{2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> @@ -416,41 +416,41 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) Gets the friendly name of a or instance. Returns the friendly name for a specific or instance. - instance. The example uses the property to obtain the friendly name of a recognition engine configuration, and then displays it in a . - -``` -private void recognizerInfoButton_Click(object sender, EventArgs e) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 }\n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - "{2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + instance. The example uses the property to obtain the friendly name of a recognition engine configuration, and then displays it in a . + +``` +private void recognizerInfoButton_Click(object sender, EventArgs e) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 }\n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + "{2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> @@ -485,41 +485,41 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) Gets the audio formats supported by a or instance. Returns a list of audio formats supported by a specific or instance. - instance. The example uses the property to obtain the encoding formats supported by a recognition engine configuration, and then displays it in a . - -``` -private void recognizerInfoButton_Click(object sender, EventArgs e) -{ - RecognizerInfo info = _recognizer.RecognizerInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); - } - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - MessageBox.Show(String.Format( - "Name: {0 }\n" + - "Description: {1} \n" + - "SupportedAudioFormats:\n" + - "{2} " + - "Culture: {3} \n" + - "AdditionalInfo: \n" + - " {4}\n", - info.Name.ToString(), - info.Description.ToString(), - AudioFormats, - info.Culture.ToString(), - AdditionalInfo)); -} -``` - + instance. The example uses the property to obtain the encoding formats supported by a recognition engine configuration, and then displays it in a . + +``` +private void recognizerInfoButton_Click(object sender, EventArgs e) +{ + RecognizerInfo info = _recognizer.RecognizerInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format(" {0}\n", fmt.EncodingFormat.ToString()); + } + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + MessageBox.Show(String.Format( + "Name: {0 }\n" + + "Description: {1} \n" + + "SupportedAudioFormats:\n" + + "{2} " + + "Culture: {3} \n" + + "AdditionalInfo: \n" + + " {4}\n", + info.Name.ToString(), + info.Description.ToString(), + AudioFormats, + info.Culture.ToString(), + AdditionalInfo)); +} +``` + ]]> diff --git a/xml/System.Speech.Recognition/SemanticResultKey.xml b/xml/System.Speech.Recognition/SemanticResultKey.xml index 30573f93789..36a213a8ac4 100644 --- a/xml/System.Speech.Recognition/SemanticResultKey.xml +++ b/xml/System.Speech.Recognition/SemanticResultKey.xml @@ -161,7 +161,7 @@ SemanticResultKey stringTest=new SemanticResultKey( new GrammarBuilder("fox")}); ``` - The `semanticResultKey` argument contains the tag used to access the which might be returned. + The `semanticResultKey` argument contains the tag used to access the that might be returned. The of the is determined by the instances provided by the `builders` parameter. @@ -275,7 +275,7 @@ SemanticResultKey stringTest=new SemanticResultKey("stringTest", "fox"}); ``` - The `semanticResultKey` argument determines the key used to access the which might be returned. + The `semanticResultKey` argument determines the key used to access the that might be returned. If you construct a using a object that contains a semantic key with an array of string objects, the of the produced by a recognition operation will be the string used in recognition. In the preceding example, this means that would be "the quick brown fox". diff --git a/xml/System.Speech.Recognition/SemanticValue.xml b/xml/System.Speech.Recognition/SemanticValue.xml index 30edc32ab31..451e421847f 100644 --- a/xml/System.Speech.Recognition/SemanticValue.xml +++ b/xml/System.Speech.Recognition/SemanticValue.xml @@ -60,158 +60,158 @@ Represents the semantic organization of a recognized phrase. - is the primary object that implements the semantic technology in System.Speech. Semantic interpretation allows grammars to define rules for use by a recognition engine to correctly interpret audio input. Semantic interpretation also enables recognition engines to organize their results so that they can be more easily processed, rather than returning only recognized words and sequences of words. - - For example, the recognition engine output "Change background to red" would have to be parsed and interpreted by an application before it could be acted upon. A object can specify a semantic interpretation to make processing clearer by specifying that the phrase has two semantic substructures, one for selecting background or foreground (represented by the text "background"), and the other for selecting color (represented by the text "red"). - - System.Speech represents the semantics of a recognition operation in a tree of objects. - - Each instance includes the following: - -- 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 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. - - ```csharp - foreach (KeyValuePair child in semantics) - { - Utils.CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); - } - ``` - - 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 ). - - objects obtained for recognized phrases without semantic structure are characterized by: - -- The lack of children ( is 0). - -- The property is `null`. - -- An artificial semantic confidence level of 1.0 (returned by ). - - Typically, applications create instances indirectly, adding them to objects by using and instances, in conjunction with and objects. - - Direct construction of a instance is useful during the creation of strongly-typed grammars. - - implements the , , and interfaces. - - - -## Examples - The following example shows a handler for a event designed to handle commands to change foreground and background color. - - The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. - - In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. - -```csharp - -newGrammar.SpeechRecognized += - delegate(object sender, SpeechRecognizedEventArgs eventArgs) - { - - // Retrieve the value of the semantic property. - bool changeBackGround = true; - string errorString = ""; - SemanticValue semantics = eventArgs.Result.Semantics; - - Color newColor = Color.Empty; - - try - { - if (semantics.Count == 0 && semantics.Value==null) - { - // Signifies recognition by a grammar with no semantics. - // Parse the string, assuming that the last word is color, - // and search for "background" or "foreground" in the input. - if (eventArgs.Result.Text.Contains("foreground")) - { - changeBackGround = false; - } - string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; - newColor = Color.FromName(cName); - - } - else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) - { - - // Determine whether to change background or foreground. - if (semantics.ContainsKey("applyChgToBackground")) - { - changeBackGround = semantics["applyChgToBackground"].Value is bool; - } - - // Get the RGB color value. - if (semantics.ContainsKey("colorStringList")) - { - newColor = Color.FromName((string)semantics["colorStringList"].Value); - } - if (semantics.ContainsKey("colorRGBValueList")) - { - newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); - } - } - else - { - - // Throw an exception if the semantics do not contain the keys we - // support. - throw(new Exception("Unsupported semantics keys found.")); - } - } - - catch (Exception exp) - { - MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); - return; - } - - // Change colors, either foreground or background. - if (changeBackGround) - { - BackColor = newColor; - float Bright = BackColor.GetBrightness(); - float Hue = BackColor.GetHue(); - float Sat = BackColor.GetSaturation(); - - // Make sure that text is readable regardless of the background. - if (BackColor.GetBrightness() <= .50) - { - ForeColor = Color.White; - } - else - { - ForeColor = Color.Black; - } - } - else - { - ForeColor = newColor; - float Bright = ForeColor.GetBrightness(); - float Hue = ForeColor.GetHue(); - float Sat = ForeColor.GetSaturation(); - - // Make sure that text is readable regardless of Foreground. - if (ForeColor.GetBrightness() <= .50) - { - BackColor = Color.White; - } - else - { - BackColor = Color.Black; - } - } - return; - }; -``` - + is the primary object that implements the semantic technology in System.Speech. Semantic interpretation allows grammars to define rules for use by a recognition engine to correctly interpret audio input. Semantic interpretation also enables recognition engines to organize their results so that they can be more easily processed, rather than returning only recognized words and sequences of words. + + For example, the recognition engine output "Change background to red" would have to be parsed and interpreted by an application before it could be acted upon. A object can specify a semantic interpretation to make processing clearer by specifying that the phrase has two semantic substructures, one for selecting background or foreground (represented by the text "background"), and the other for selecting color (represented by the text "red"). + + System.Speech represents the semantics of a recognition operation in a tree of objects. + + Each instance includes the following: + +- 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 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. + + ```csharp + foreach (KeyValuePair child in semantics) + { + Utils.CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); + } + ``` + + 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 ). + + objects obtained for recognized phrases without semantic structure are characterized by: + +- The lack of children ( is 0). + +- The property is `null`. + +- An artificial semantic confidence level of 1.0 (returned by ). + + Typically, applications create instances indirectly, adding them to objects by using and instances, in conjunction with and objects. + + Direct construction of a instance is useful during the creation of strongly-typed grammars. + + implements the , , and interfaces. + + + +## Examples + The following example shows a handler for a event designed to handle commands to change foreground and background color. + + The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. + + In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. + +```csharp + +newGrammar.SpeechRecognized += + delegate(object sender, SpeechRecognizedEventArgs eventArgs) + { + + // Retrieve the value of the semantic property. + bool changeBackGround = true; + string errorString = ""; + SemanticValue semantics = eventArgs.Result.Semantics; + + Color newColor = Color.Empty; + + try + { + if (semantics.Count == 0 && semantics.Value==null) + { + // Signifies recognition by a grammar with no semantics. + // Parse the string, assuming that the last word is color, + // and search for "background" or "foreground" in the input. + if (eventArgs.Result.Text.Contains("foreground")) + { + changeBackGround = false; + } + string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; + newColor = Color.FromName(cName); + + } + else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) + { + + // Determine whether to change background or foreground. + if (semantics.ContainsKey("applyChgToBackground")) + { + changeBackGround = semantics["applyChgToBackground"].Value is bool; + } + + // Get the RGB color value. + if (semantics.ContainsKey("colorStringList")) + { + newColor = Color.FromName((string)semantics["colorStringList"].Value); + } + if (semantics.ContainsKey("colorRGBValueList")) + { + newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); + } + } + else + { + + // Throw an exception if the semantics do not contain the keys we + // support. + throw(new Exception("Unsupported semantics keys found.")); + } + } + + catch (Exception exp) + { + MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); + return; + } + + // Change colors, either foreground or background. + if (changeBackGround) + { + BackColor = newColor; + float Bright = BackColor.GetBrightness(); + float Hue = BackColor.GetHue(); + float Sat = BackColor.GetSaturation(); + + // Make sure that text is readable regardless of the background. + if (BackColor.GetBrightness() <= .50) + { + ForeColor = Color.White; + } + else + { + ForeColor = Color.Black; + } + } + else + { + ForeColor = newColor; + float Bright = ForeColor.GetBrightness(); + float Hue = ForeColor.GetHue(); + float Sat = ForeColor.GetSaturation(); + + // Make sure that text is readable regardless of Foreground. + if (ForeColor.GetBrightness() <= .50) + { + BackColor = Color.White; + } + else + { + BackColor = Color.Black; + } + } + return; + }; +``` + ]]> @@ -226,11 +226,11 @@ newGrammar.SpeechRecognized += Initializes a new instance of the class. - objects explicitly, except to support the building of strongly-typed grammars. - + objects explicitly, except to support the building of strongly-typed grammars. + ]]> @@ -256,17 +256,17 @@ newGrammar.SpeechRecognized += The information to be stored in the object. Initializes a new instance of the class and specifies a semantic value. - property on a instance. - - The value of the property for the instance will be set to -1. - - A constructed with this method cannot be referenced by key name. - + property on a instance. + + The value of the property for the instance will be set to -1. + + A constructed with this method cannot be referenced by key name. + ]]> @@ -296,15 +296,15 @@ newGrammar.SpeechRecognized += A containing an estimate of the certainty of semantic analysis. Initializes a new instance of the class and specifies a semantic value, a key name, and a confidence level. - property on a instance. - - The `confidence` parameter (returned by the property on a instance), should be between 0.0 and 1.0. - + property on a instance. + + The `confidence` parameter (returned by the property on a instance), should be between 0.0 and 1.0. + ]]> @@ -336,48 +336,48 @@ newGrammar.SpeechRecognized += Returns a relative measure of the certainty as to the correctness of the semantic parsing that returned the current instance of . Returns a that is a relative measure of the certainty of semantic parsing that returned the current instance of . - 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. - - - -## Examples - The following example is used to recursively traverse and then display information (including confidence) as a , or as the nodes making up the tree structure of the semantics used to recognize a phrase. - -```csharp -internal static void CreateSemanticsTreeNodes( - TreeNodeCollection nodes, - SemanticValue semantics, - String name) -{ - string semanticsText = - String.Format(" {0} (Confidence {1})", name,semantics.Confidence); - - // Format integers as hexadecimal. - if (semantics.Value == null ) - { - semanticsText = semanticsText + " = null"; - } - else if (semantics.Value.GetType() == typeof(int)) - { - semanticsText = String.Format("{0} = {1:X} ", semanticsText, semantics.Value); - } - else - { - semanticsText = semanticsText + " = " + semantics.Value.ToString(); - } - - TreeNode semanticsNode = new TreeNode(semanticsText); - foreach (KeyValuePair child in semantics) - { - CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); - } - nodes.Add(semanticsNode); -} -``` - + 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. + + + +## Examples + The following example is used to recursively traverse and then display information (including confidence) as a , or as the nodes making up the tree structure of the semantics used to recognize a phrase. + +```csharp +internal static void CreateSemanticsTreeNodes( + TreeNodeCollection nodes, + SemanticValue semantics, + String name) +{ + string semanticsText = + String.Format(" {0} (Confidence {1})", name,semantics.Confidence); + + // Format integers as hexadecimal. + if (semantics.Value == null ) + { + semanticsText = semanticsText + " = null"; + } + else if (semantics.Value.GetType() == typeof(int)) + { + semanticsText = String.Format("{0} = {1:X} ", semanticsText, semantics.Value); + } + else + { + semanticsText = semanticsText + " = " + semantics.Value.ToString(); + } + + TreeNode semanticsNode = new TreeNode(semanticsText); + foreach (KeyValuePair child in semantics) + { + CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); + } + nodes.Add(semanticsNode); +} +``` + ]]> @@ -408,7 +408,7 @@ internal static void CreateSemanticsTreeNodes( An instance of instantiated for a given value of a key string and a instance. Indicates whether the current instance collection contains a specific key and a specific instance of expressed as a key/value pair. - Returns a which is if the current contains an instance of KeyValuePair<String, SemanticValue> for a specified value of the key string and the . Otherwise, is returned. + if the current contains an instance of KeyValuePair<String, SemanticValue> for a specified value of the key string and the ; otherwise, . To be added. @@ -441,118 +441,118 @@ internal static void CreateSemanticsTreeNodes( Indicates whether the current instance collection contains a child instance with a given key string. Returns a , if a child instance tagged with the string is found, if not. - before using with a given instance of . - - - -## Examples - The following example shows a handler for a event designed to handle commands to change foreground and background color. - - After handling phrases that are recognized but have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then processes the semantically organized data. - -```csharp - -newGrammar.SpeechRecognized += - delegate(object sender, SpeechRecognizedEventArgs eventArgs) - { - - // Retrieve the value of the semantic property. - bool changeBackGround = true; - string errorString = ""; - SemanticValue semantics = eventArgs.Result.Semantics; - - Color newColor = Color.Empty; - - try - { - if (semantics.Count == 0 && semantics.Value==null) - { - - // Signifies recognition by a grammar with no semantics. - // Parse the string, assuming that the last word is color, - // searching for background or foreground in input. - if (eventArgs.Result.Text.Contains("foreground")) - { - changeBackGround = false; - } - string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; - newColor = Color.FromName(cName); - - } - else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) - { - - // Determine whether to change background or foreground. - if (semantics.ContainsKey("applyChgToBackground")) - { - changeBackGround = semantics["applyChgToBackground"].Value is bool; - } - - // Get the RGB color value. - if (semantics.ContainsKey("colorStringList")) - { - newColor = Color.FromName((string)semantics["colorStringList"].Value); - } - if (semantics.ContainsKey("colorRGBValueList")) - { - newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); - } - } - else - { - - // Throw an exception if the semantics do not contain the keys we - // support. - throw(new Exception("Unsupported semantics keys found.")); - } - } - - catch (Exception exp) - { - MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); - return; - } - - // Change colors, either foreground or background. - if (changeBackGround) - { - BackColor = newColor; - float Bright = BackColor.GetBrightness(); - float Hue = BackColor.GetHue(); - float Sat = BackColor.GetSaturation(); - // Make sure that text is readable regardless of background. - if (BackColor.GetBrightness() <= .50) - { - ForeColor = Color.White; - } - else - { - ForeColor = Color.Black; - } - } - else - { - ForeColor = newColor; - float Bright = ForeColor.GetBrightness(); - float Hue = ForeColor.GetHue(); - float Sat = ForeColor.GetSaturation(); - // Make sure that text is readable regardless of Foreground. - if (ForeColor.GetBrightness() <= .50) - { - BackColor = Color.White; - } - else - { - BackColor = Color.Black; - } - } - return; - }; -``` - + before using with a given instance of . + + + +## Examples + The following example shows a handler for a event designed to handle commands to change foreground and background color. + + After handling phrases that are recognized but have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then processes the semantically organized data. + +```csharp + +newGrammar.SpeechRecognized += + delegate(object sender, SpeechRecognizedEventArgs eventArgs) + { + + // Retrieve the value of the semantic property. + bool changeBackGround = true; + string errorString = ""; + SemanticValue semantics = eventArgs.Result.Semantics; + + Color newColor = Color.Empty; + + try + { + if (semantics.Count == 0 && semantics.Value==null) + { + + // Signifies recognition by a grammar with no semantics. + // Parse the string, assuming that the last word is color, + // searching for background or foreground in input. + if (eventArgs.Result.Text.Contains("foreground")) + { + changeBackGround = false; + } + string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; + newColor = Color.FromName(cName); + + } + else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) + { + + // Determine whether to change background or foreground. + if (semantics.ContainsKey("applyChgToBackground")) + { + changeBackGround = semantics["applyChgToBackground"].Value is bool; + } + + // Get the RGB color value. + if (semantics.ContainsKey("colorStringList")) + { + newColor = Color.FromName((string)semantics["colorStringList"].Value); + } + if (semantics.ContainsKey("colorRGBValueList")) + { + newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); + } + } + else + { + + // Throw an exception if the semantics do not contain the keys we + // support. + throw(new Exception("Unsupported semantics keys found.")); + } + } + + catch (Exception exp) + { + MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); + return; + } + + // Change colors, either foreground or background. + if (changeBackGround) + { + BackColor = newColor; + float Bright = BackColor.GetBrightness(); + float Hue = BackColor.GetHue(); + float Sat = BackColor.GetSaturation(); + // Make sure that text is readable regardless of background. + if (BackColor.GetBrightness() <= .50) + { + ForeColor = Color.White; + } + else + { + ForeColor = Color.Black; + } + } + else + { + ForeColor = newColor; + float Bright = ForeColor.GetBrightness(); + float Hue = ForeColor.GetHue(); + float Sat = ForeColor.GetSaturation(); + // Make sure that text is readable regardless of Foreground. + if (ForeColor.GetBrightness() <= .50) + { + BackColor = Color.White; + } + else + { + BackColor = Color.Black; + } + } + return; + }; +``` + ]]> @@ -581,120 +581,120 @@ newGrammar.SpeechRecognized += Returns the number of child objects under the current instance. The number of child objects under the current . - value of zero, as well as a of `null`. - - - -## Examples - The following example shows a handler for a event designed to handle commands to change foreground and background color. - - The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. - - In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. - -```csharp - -newGrammar.SpeechRecognized += - delegate(object sender, SpeechRecognizedEventArgs eventArgs) - { - - // Retrieve the value of the semantic property. - bool changeBackGround = true; - string errorString = ""; - SemanticValue semantics = eventArgs.Result.Semantics; - - Color newColor = Color.Empty; - - try - { - if (semantics.Count == 0 && semantics.Value==null) - { - // Signifies recognition by a grammar with no semantics. - // Parse the string, assuming that the last word is color, - // searching for background or foreground in input. - if (eventArgs.Result.Text.Contains("foreground")) - { - changeBackGround = false; - } - string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; - newColor = Color.FromName(cName); - - } - else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) - { - - // Determine whether to change background or foreground. - if (semantics.ContainsKey("applyChgToBackground")) - { - changeBackGround = semantics["applyChgToBackground"].Value is bool; - } - - // Get the RGB color value. - if (semantics.ContainsKey("colorStringList")) - { - newColor = Color.FromName((string)semantics["colorStringList"].Value); - } - if (semantics.ContainsKey("colorRGBValueList")) - { - newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); - } - } - else - { - - // Throw an exception if the semantics do not contain the keys we - // support. - throw(new Exception("Unsupported semantics keys found.")); - } - } - - catch (Exception exp) - { - MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); - return; - } - - // Change colors, either foreground or background. - if (changeBackGround) - { - BackColor = newColor; - float Bright = BackColor.GetBrightness(); - float Hue = BackColor.GetHue(); - float Sat = BackColor.GetSaturation(); - // Make sure that text is readable regardless of background. - if (BackColor.GetBrightness() <= .50) - { - ForeColor = Color.White; - } - else - { - ForeColor = Color.Black; - } - } - else - { - ForeColor = newColor; - float Bright = ForeColor.GetBrightness(); - float Hue = ForeColor.GetHue(); - float Sat = ForeColor.GetSaturation(); - - // Make sure that text is readable regardless of Foreground. - if (ForeColor.GetBrightness() <= .50) - { - BackColor = Color.White; - } - else - { - BackColor = Color.Black; - } - } - return; - }; -``` - + value of zero, as well as a of `null`. + + + +## Examples + The following example shows a handler for a event designed to handle commands to change foreground and background color. + + The handler identifies recognized phrases that have no underlying semantic structure by detecting a of zero and a of `null`. This recognition output is then processed directly by parsing the raw text. + + In other cases, the handler uses keys to obtain the RGB components of a color name, to determine whether the command will change the foreground or background, or to indicate that no valid key was found. + +```csharp + +newGrammar.SpeechRecognized += + delegate(object sender, SpeechRecognizedEventArgs eventArgs) + { + + // Retrieve the value of the semantic property. + bool changeBackGround = true; + string errorString = ""; + SemanticValue semantics = eventArgs.Result.Semantics; + + Color newColor = Color.Empty; + + try + { + if (semantics.Count == 0 && semantics.Value==null) + { + // Signifies recognition by a grammar with no semantics. + // Parse the string, assuming that the last word is color, + // searching for background or foreground in input. + if (eventArgs.Result.Text.Contains("foreground")) + { + changeBackGround = false; + } + string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; + newColor = Color.FromName(cName); + + } + else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) + { + + // Determine whether to change background or foreground. + if (semantics.ContainsKey("applyChgToBackground")) + { + changeBackGround = semantics["applyChgToBackground"].Value is bool; + } + + // Get the RGB color value. + if (semantics.ContainsKey("colorStringList")) + { + newColor = Color.FromName((string)semantics["colorStringList"].Value); + } + if (semantics.ContainsKey("colorRGBValueList")) + { + newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); + } + } + else + { + + // Throw an exception if the semantics do not contain the keys we + // support. + throw(new Exception("Unsupported semantics keys found.")); + } + } + + catch (Exception exp) + { + MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); + return; + } + + // Change colors, either foreground or background. + if (changeBackGround) + { + BackColor = newColor; + float Bright = BackColor.GetBrightness(); + float Hue = BackColor.GetHue(); + float Sat = BackColor.GetSaturation(); + // Make sure that text is readable regardless of background. + if (BackColor.GetBrightness() <= .50) + { + ForeColor = Color.White; + } + else + { + ForeColor = Color.Black; + } + } + else + { + ForeColor = newColor; + float Bright = ForeColor.GetBrightness(); + float Hue = ForeColor.GetHue(); + float Sat = ForeColor.GetSaturation(); + + // Make sure that text is readable regardless of Foreground. + if (ForeColor.GetBrightness() <= .50) + { + BackColor = Color.White; + } + else + { + BackColor = Color.Black; + } + } + return; + }; +``` + ]]> @@ -785,122 +785,122 @@ newGrammar.SpeechRecognized += Returns child instances that belong to the current . Returns a child of the current that can be indexed as part of a key value pair: KeyValuePair<String,SemanticValue>. - is read-only and generates exceptions if members are modified. - - 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. - + is read-only and generates exceptions if members are modified. + + 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. - -## 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. - - The use of is highlighted below. - -```csharp - -newGrammar.SpeechRecognized += - delegate(object sender, SpeechRecognizedEventArgs eventArgs) - { - - // Retrieve the value of the semantic property. - bool changeBackGround = true; - string errorString = ""; - SemanticValue semantics = eventArgs.Result.Semantics; - - Color newColor = Color.Empty; - - try - { - if (semantics.Count == 0 && semantics.Value==null) - { - // Signifies recognition by a grammar with no semantics. - // Parse the string, assuming that the last word is color, - // searching for background or foreground in input. - if (eventArgs.Result.Text.Contains("foreground")) - { - changeBackGround = false; - } - string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; - newColor = Color.FromName(cName); - - } - else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) - { - - // Determine whether to change background or foreground. - if (semantics.ContainsKey("applyChgToBackground")) - { - changeBackGround = semantics["applyChgToBackground"].Value is bool; - } - - // Get the RGB color value. - if (semantics.ContainsKey("colorStringList")) - { - newColor = Color.FromName((string)semantics["colorStringList"].Value); - } - if (semantics.ContainsKey("colorRGBValueList")) - { - newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); - } - } - else - { - - // Throw an exception if the semantics do not contain the keys we - // support. - throw(new Exception("Unsupported semantic keys found.")); - } - } - - catch (Exception exp) - { - MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); - return; - } - - // Change colors, either foreground or background. - if (changeBackGround) - { - BackColor = newColor; - float Bright = BackColor.GetBrightness(); - float Hue = BackColor.GetHue(); - float Sat = BackColor.GetSaturation(); - // Make sure that text is readable regardless of background. - if (BackColor.GetBrightness() <= .50) - { - ForeColor = Color.White; - } - else - { - ForeColor = Color.Black; - } - } - else - { - ForeColor = newColor; - float Bright = ForeColor.GetBrightness(); - float Hue = ForeColor.GetHue(); - float Sat = ForeColor.GetSaturation(); - - // Make sure that text is readable regardless of the foreground. - if (ForeColor.GetBrightness() <= .50) - { - BackColor = Color.White; - } - else - { - BackColor = Color.Black; - } - } - return; - }; -``` - + +## 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. + + The use of is highlighted below. + +```csharp + +newGrammar.SpeechRecognized += + delegate(object sender, SpeechRecognizedEventArgs eventArgs) + { + + // Retrieve the value of the semantic property. + bool changeBackGround = true; + string errorString = ""; + SemanticValue semantics = eventArgs.Result.Semantics; + + Color newColor = Color.Empty; + + try + { + if (semantics.Count == 0 && semantics.Value==null) + { + // Signifies recognition by a grammar with no semantics. + // Parse the string, assuming that the last word is color, + // searching for background or foreground in input. + if (eventArgs.Result.Text.Contains("foreground")) + { + changeBackGround = false; + } + string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text; + newColor = Color.FromName(cName); + + } + else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) + { + + // Determine whether to change background or foreground. + if (semantics.ContainsKey("applyChgToBackground")) + { + changeBackGround = semantics["applyChgToBackground"].Value is bool; + } + + // Get the RGB color value. + if (semantics.ContainsKey("colorStringList")) + { + newColor = Color.FromName((string)semantics["colorStringList"].Value); + } + if (semantics.ContainsKey("colorRGBValueList")) + { + newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value); + } + } + else + { + + // Throw an exception if the semantics do not contain the keys we + // support. + throw(new Exception("Unsupported semantic keys found.")); + } + } + + catch (Exception exp) + { + MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message)); + return; + } + + // Change colors, either foreground or background. + if (changeBackGround) + { + BackColor = newColor; + float Bright = BackColor.GetBrightness(); + float Hue = BackColor.GetHue(); + float Sat = BackColor.GetSaturation(); + // Make sure that text is readable regardless of background. + if (BackColor.GetBrightness() <= .50) + { + ForeColor = Color.White; + } + else + { + ForeColor = Color.Black; + } + } + else + { + ForeColor = newColor; + float Bright = ForeColor.GetBrightness(); + float Hue = ForeColor.GetHue(); + float Sat = ForeColor.GetSaturation(); + + // Make sure that text is readable regardless of the foreground. + if (ForeColor.GetBrightness() <= .50) + { + BackColor = Color.White; + } + else + { + BackColor = Color.Black; + } + } + return; + }; +``` + ]]> No child member of the current instance of has a key matching the parameter. @@ -1283,48 +1283,48 @@ This member is an explicit interface member implementation. It can be used only A read-only property that returns the information contained in the current . Returns an instance containing the information stored in the current instance. - of `null` and a property of zero. - - - -## Examples - The following example is used to recursively traverse and then display information (including confidence) as a , or as the nodes making up the tree structure of the semantics used to recognize a phrase. - -```csharp -internal static void CreateSemanticsTreeNodes( - TreeNodeCollection nodes, - SemanticValue semantics, - String name) -{ - string semanticsText = - String.Format(" {0} ( Confidence {1})", name,semantics.Confidence); - - // Format integers as hexadecimal. - if (semantics.Value == null ) - { - semanticsText = semanticsText + " = null"; - } - else if (semantics.Value.GetType() == typeof(int)) - { - semanticsText = String.Format("{0} = {1:X} ", semanticsText, semantics.Value); - } - else - { - semanticsText = semanticsText + " = " + semantics.Value.ToString(); - } - - TreeNode semanticsNode = new TreeNode(semanticsText); - foreach (KeyValuePair child in semantics) - { - CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); - } - nodes.Add(semanticsNode); -} -``` - + of `null` and a property of zero. + + + +## Examples + The following example is used to recursively traverse and then display information (including confidence) as a , or as the nodes making up the tree structure of the semantics used to recognize a phrase. + +```csharp +internal static void CreateSemanticsTreeNodes( + TreeNodeCollection nodes, + SemanticValue semantics, + String name) +{ + string semanticsText = + String.Format(" {0} ( Confidence {1})", name,semantics.Confidence); + + // Format integers as hexadecimal. + if (semantics.Value == null ) + { + semanticsText = semanticsText + " = null"; + } + else if (semantics.Value.GetType() == typeof(int)) + { + semanticsText = String.Format("{0} = {1:X} ", semanticsText, semantics.Value); + } + else + { + semanticsText = semanticsText + " = " + semantics.Value.ToString(); + } + + TreeNode semanticsNode = new TreeNode(semanticsText); + foreach (KeyValuePair child in semantics) + { + CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key); + } + nodes.Add(semanticsNode); +} +``` + ]]> diff --git a/xml/System.Speech.Recognition/SubsetMatchingMode.xml b/xml/System.Speech.Recognition/SubsetMatchingMode.xml index 85b6df4e0ae..dfbd036abbe 100644 --- a/xml/System.Speech.Recognition/SubsetMatchingMode.xml +++ b/xml/System.Speech.Recognition/SubsetMatchingMode.xml @@ -21,113 +21,112 @@ Enumerates values of subset matching mode. - member used as an argument to the or constructors, or the method. - - The following illustrates how each of the members affects recognition when used in a grammar that contains the phrase "a car the truck a boat that plane". - - **OrderedSubset** - - This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: - -- One or more words in the phrase are recognized in the audio input. - -- The relative order of those recognized words is the same as in the phrase. - -- Matched words may consist of only prepositions and articles. - - Adding the phrase "a car the truck a boat that plane" to a grammar using OrderedSubset mode produces the following result on recognition: - -|**Input Phrase**|**Result**| -|----------------------|----------------| -|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the that plane"|The entire phrase "a car the truck a boat that plane" is recognized. A recognized subset is not required to be a sequence of the original string.| -|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| -|"a the"|The entire phrase "a car the truck a boat that plane" is recognized. Prepositions and articles are used for recognition.| - - **OrderedSubsetContentRequired** - - This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: - -- One or more words in the phrase are recognized in the audio input, and - -- The relative order of those recognized words is the same as in the phrase. - -- Matched words cannot consist of only prepositions and articles. - - Adding the phrase "a car the truck a boat that plane" to a grammar using OrderedSubsetContentRequired mode produces the following result on recognition: - -|**Input Phrase**|**Result**| -|----------------------|----------------| -|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the that plane"|The entire phrase "a car the truck a boat that plane" is recognized. A recognized subset is not required to be a sequence of the original string.| -|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| -|"a the"|Recognition is not successful. Speech input must contain words other than articles and prepositions.| - - **Subsequence:** - - This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: - -- One or more words in the phrase are recognized in the audio input as a sequence of the phrase, and - -- The relative order of those recognized words is the same as in the phrase. - -- Matched words may consist of only prepositions and articles. - - Adding the phrase "a car the truck a boat that plane" to a grammar using Subsequence mode produces the following result on recognition: - -|**Input Phrase**|**Result**| -|----------------------|----------------| -|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the that plane"|Recognition is not successful. A recognized subset is required to be a sequence of the original string.| -|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| -|"a the"|The entire phrase "a car the truck a boat that plane" is recognized. Prepositions and articles are used for recognition.| - - **SubsequenceContentRequired** - - This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: - -- One or more words in the match string are recognized in the audio input as a sequence of the phrase. - -- Matched words cannot consist of only prepositions and articles. - - Adding the phrase "a car the truck a boat that plane" to a grammar using SubsequenceContentRequired mode produces the following result on recognition: - -|**Input Phrase**|**Result**| -|----------------------|----------------| -|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| -|"a car the that plane"|Recognition is not successful. A recognized subset is required to be a sequence of the original string.| -|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| -|"a the"|Recognition is not successful. Speech input must contain words other than articles and prepositions.| - - - -## Examples - Below is a test routine which generates four objects, using the same phrase, for each of the `SubsetMatchingModes`. These objects can then be tested. - -``` -private void CreateSubsetMatchTest() -{ - foreach ( System.Speech.Recognition.SubsetMatchingMode mode - in Enum.GetValues(typeof(System.Speech.Recognition.SubsetMatchingMode))) - { - GrammarBuilder gb = new GrammarBuilder("a car the truck a boat that plane",mode); - Grammar grammar = new Grammar(gb); - grammar.Name = mode.ToString(); - grammar.Enabled=true; - _recognizer.LoadGrammar(grammar); - } -} -``` - + member used as an argument to the or constructors, or the method. + + The following illustrates how each of the members affects recognition when used in a grammar that contains the phrase "a car the truck a boat that plane". + + **OrderedSubset** + + This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: + +- One or more words in the phrase are recognized in the audio input. + +- The relative order of those recognized words is the same as in the phrase. + +- Matched words may consist of only prepositions and articles. + + Adding the phrase "a car the truck a boat that plane" to a grammar using OrderedSubset mode produces the following result on recognition: + +|**Input Phrase**|**Result**| +|----------------------|----------------| +|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the that plane"|The entire phrase "a car the truck a boat that plane" is recognized. A recognized subset is not required to be a sequence of the original string.| +|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| +|"a the"|The entire phrase "a car the truck a boat that plane" is recognized. Prepositions and articles are used for recognition.| + + **OrderedSubsetContentRequired** + + This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: + +- One or more words in the phrase are recognized in the audio input, and + +- The relative order of those recognized words is the same as in the phrase. + +- Matched words cannot consist of only prepositions and articles. + + Adding the phrase "a car the truck a boat that plane" to a grammar using OrderedSubsetContentRequired mode produces the following result on recognition: + +|**Input Phrase**|**Result**| +|----------------------|----------------| +|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the that plane"|The entire phrase "a car the truck a boat that plane" is recognized. A recognized subset is not required to be a sequence of the original string.| +|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| +|"a the"|Recognition is not successful. Speech input must contain words other than articles and prepositions.| + + **Subsequence:** + + This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: + +- One or more words in the phrase are recognized in the audio input as a sequence of the phrase, and + +- The relative order of those recognized words is the same as in the phrase. + +- Matched words may consist of only prepositions and articles. + + Adding the phrase "a car the truck a boat that plane" to a grammar using Subsequence mode produces the following result on recognition: + +|**Input Phrase**|**Result**| +|----------------------|----------------| +|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the that plane"|Recognition is not successful. A recognized subset is required to be a sequence of the original string.| +|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| +|"a the"|The entire phrase "a car the truck a boat that plane" is recognized. Prepositions and articles are used for recognition.| + + **SubsequenceContentRequired** + + This mode indicates that a subset of the phrase will be used to successfully recognize the entire phrase if the following are true: + +- One or more words in the match string are recognized in the audio input as a sequence of the phrase. + +- Matched words cannot consist of only prepositions and articles. + + Adding the phrase "a car the truck a boat that plane" to a grammar using SubsequenceContentRequired mode produces the following result on recognition: + +|**Input Phrase**|**Result**| +|----------------------|----------------| +|"a car the truck a boat that plane"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the truck a boat"|The entire phrase "a car the truck a boat that plane" is recognized.| +|"a car the that plane"|Recognition is not successful. A recognized subset is required to be a sequence of the original string.| +|"a car the boat a truck that plane"|Recognition is not successful. The words are out of order.| +|"a the"|Recognition is not successful. Speech input must contain words other than articles and prepositions.| + +## Examples + +Following is a test routine that generates four objects, using the same phrase, for each of the `SubsetMatchingModes`. These objects can then be tested. + +``` +private void CreateSubsetMatchTest() +{ + foreach ( System.Speech.Recognition.SubsetMatchingMode mode + in Enum.GetValues(typeof(System.Speech.Recognition.SubsetMatchingMode))) + { + GrammarBuilder gb = new GrammarBuilder("a car the truck a boat that plane",mode); + Grammar grammar = new Grammar(gb); + grammar.Name = mode.ToString(); + grammar.Enabled=true; + _recognizer.LoadGrammar(grammar); + } +} +``` + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml index c5442c4a3af..be9db58db69 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml @@ -32,78 +32,78 @@ Used to specify the type of event, and its arguments (if any) to be generated as part of the rendering of text to speech by a custom synthetic speech engine. - instance to member of the engine site object passed to implementations 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. - -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); - -} -``` - + instance to member of the engine site object passed to implementations 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. + +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); + +} +``` + ]]> @@ -137,90 +137,90 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si An instance of indicating the sort of Speech platform event the object is to handle. An instance of indicating how the reference of is to be interpreted, and, by implication, the use of . - An integer value to be passed to the Speech platform when the event requested by the instance of to be constructed is generated. - + An integer value to be passed to the Speech platform when the event requested by the instance of to be constructed is generated. + The exact meaning of this integer is implicitly determined by the value of . - A instance referencing an object. to be passed to the Speech platform when the event requested by the instance of to be constructed is generated. - - The type which must be referenced is explicitly defined by the value . The value . + A instance referencing an object. to be passed to the Speech platform when the event requested by the instance of to be constructed is generated. + + The type that must be referenced is explicitly defined by the value . The value . Constructs an appropriate . - used for `eventId`. - - 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 . - - - -## 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. - -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); - -} -``` - + used for `eventId`. + + 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 . + + + +## 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. + +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); + +} +``` + ]]> @@ -320,79 +320,79 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets and set the Speech platform event which an instance of is used to request. Returns a member of as a , indicating the event type the object is to generate. - , 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 are used to log the event generated through the `LogSpeechEvent` method. - -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. + + The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. + +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); + +} +``` + ]]> @@ -512,86 +512,86 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets and set the value ( in the constructor) to be passed to the Speech platform to generate an event the current instance of is used to request. Returns the to be passed to Speech platform when the event specified by the current instance of is generated. - property of are uniquely determined by the values of the and properties the instance. - - For detailed information on how use , see documentation for . - - - -## 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. - -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 are used to log the event generated through the `LogSpeechEvent` method. - -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); - -} -``` - + property of are uniquely determined by the values of the and properties the instance. + + For detailed information on how use , see documentation for . + + + +## 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. + +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 are used to log the event generated through the `LogSpeechEvent` method. + +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); + +} +``` + ]]> @@ -623,86 +623,86 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets and set the instance ( in the constructor) referencing the object to be passed to the Speech platform to generate an event the current instance of is used to request. Returns the referencing the object to be passed to Speech platform when the event specified by the current instance of is generated. - property of are uniquely determined by the values of the and properties the instance. - - For detailed information on how use , see documentation for . - - - -## 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. - -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 are used to log the event generated through the `LogSpeechEvent` method. - -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); - -} -``` - + property of are uniquely determined by the values of the and properties the instance. + + For detailed information on how use , see documentation for . + + + +## 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. + +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 are used to log the event generated through the `LogSpeechEvent` method. + +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); + +} +``` + ]]> @@ -734,86 +734,86 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Returns the data type of the object pointed to by the returned by the parameter on the current object. A value corresponding to a member of the enumeration and indicating the data type of the object pointed to by the returned by the parameter and used as the second argument for the constructor of the current object. - property of are uniquely determined by the values of the and properties the instance. - - For detailed information on how use , see documentation for . - - - -## 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. - -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 are used to log the event generated through the `LogSpeechEvent` method. - -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); - -} -``` - + property of are uniquely determined by the values of the and properties the instance. + + For detailed information on how use , see documentation for . + + + +## 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. + +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 are used to log the event generated through the `LogSpeechEvent` method. + +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.Transactions/Enlistment.xml b/xml/System.Transactions/Enlistment.xml index bcd7b8f77f5..73d2a3f7d22 100644 --- a/xml/System.Transactions/Enlistment.xml +++ b/xml/System.Transactions/Enlistment.xml @@ -43,23 +43,23 @@ Facilitates communication between an enlisted transaction participant and the transaction manager during the final phase of the transaction. - and methods of the object are invoked to enlist a participant in a transaction, they return this object describing the enlistment. - - During the final phase of the transaction commit, the transaction manager passes this object to a resource manager implementing the interface that has enlisted in a transaction. Specifically, the transaction manager calls either the or the method of the participant, depending on whether the latter has decided to commit or roll back the transaction. The participant should call the method of this object to let the transaction manager know that it has completed its work. - - An enlistment can call the method at anytime before it has called in the prepare phase. 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. Note that, after the method is called, the enlisted participant receives no further notifications from the transaction manager. - - - -## Examples - The following example shows an implementation of the interface, and when the method should be called. - + and methods of the object are invoked to enlist a participant in a transaction, they return this object describing the enlistment. + + During the final phase of the transaction commit, the transaction manager passes this object to a resource manager implementing the interface that has enlisted in a transaction. Specifically, the transaction manager calls either the or the method of the participant, depending on whether the latter has decided to commit or roll back the transaction. The participant should call the method of this object to let the transaction manager know that it has completed its work. + + An enlistment can call the method at anytime before it has called in the prepare phase. 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. Note that, after the method is called, the enlisted participant receives no further notifications from the transaction manager. + + + +## Examples + The following example shows an implementation of the interface, and when the method should be called. + :::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. @@ -106,15 +106,15 @@ Indicates that the transaction participant has completed its work. - , or method of the participant, depending on whether the transaction is to be committed or rolled back. The resource manager should perform any work necessary to finish the transaction and then inform the transaction manager that it has finished by calling the method on the `enlistment` parameter. - - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the respective notification call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. - - An enlistment can call the method at anytime before it has called in the prepare phase. 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. Note that, after this method is called, the enlisted participant receives no further notifications from the transaction manager. - + , or method of the participant, depending on whether the transaction is to be committed or rolled back. The resource manager should perform any work necessary to finish the transaction and then inform the transaction manager that it has finished by calling the method on the `enlistment` parameter. + + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the respective notification call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + + An enlistment can call the method at anytime before it has called in the prepare phase. 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. Note that, after this method is called, the enlisted participant receives no further notifications from the transaction manager. + ]]> diff --git a/xml/System.Transactions/IEnlistmentNotification.xml b/xml/System.Transactions/IEnlistmentNotification.xml index 6dba30beb75..812e79d8731 100644 --- a/xml/System.Transactions/IEnlistmentNotification.xml +++ b/xml/System.Transactions/IEnlistmentNotification.xml @@ -41,33 +41,33 @@ Describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation. - class defines a set of methods whose names begin with `Enlist` that provide this functionality. The different `Enlist` methods correspond to the different types of enlistment that a resource manager may have. - - This class describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation. For each resource manager's implementation of the interface, you should enlist it using the method or the method of the class, depending on whether your resource is volatile or durable. For more information on enlistment and 2PC, see [Enlisting Resources as Participants in a Transaction](/dotnet/framework/data/transactions/enlisting-resources-as-participants-in-a-transaction) and [Committing a Transaction in Single-Phase and Multi-Phase](/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase) respectively. - - The transaction manager notifies the enlisted object at different phases of the Two Phase Commit Protocol by the following methods. - -|Method|Description| -|------------|-----------------| -||This method of an enlisted object is used as a callback by the Transaction Manager during the first phase of a transaction, when the transaction manager asks participants whether they can commit the transaction.| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is committed.| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is aborted (that is, rolled back).| -||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is in doubt.| - + class defines a set of methods whose names begin with `Enlist` that provide this functionality. The different `Enlist` methods correspond to the different types of enlistment that a resource manager may have. + + This class describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation. For each resource manager's implementation of the interface, you should enlist it using the method or the method of the class, depending on whether your resource is volatile or durable. For more information on enlistment and 2PC, see [Enlisting Resources as Participants in a Transaction](/dotnet/framework/data/transactions/enlisting-resources-as-participants-in-a-transaction) and [Committing a Transaction in Single-Phase and Multi-Phase](/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase) respectively. + + The transaction manager notifies the enlisted object at different phases of the Two Phase Commit Protocol by the following methods. + +|Method|Description| +|------------|-----------------| +||This method of an enlisted object is used as a callback by the Transaction Manager during the first phase of a transaction, when the transaction manager asks participants whether they can commit the transaction.| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is committed.| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is aborted (that is, rolled back).| +||This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is in doubt.| + > [!NOTE] -> You should be aware that notifications might not be sent sequentially, or in a particular order. - - - -## Examples - The following example shows an implementation of this interface, as well as enlisting the object as a participant in a transaction using the method. - +> You should be aware that notifications might not be sent sequentially, or in a particular order. + + + +## Examples + The following example shows an implementation of this interface, as well as enlisting the object as a participant in a transaction using the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet1"::: + ]]> @@ -116,15 +116,15 @@ An object used to send a response to the transaction manager. Notifies an enlisted object that a transaction is being committed. - method on the `enlistment` parameter. - - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. - + method on the `enlistment` parameter. + + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + ]]> @@ -170,18 +170,18 @@ An object used to send a response to the transaction manager. Notifies an enlisted object that the status of a transaction is in doubt. - is considered to be a final state for a transaction, you should not call or after calling . - + is considered to be a final state for a transaction, you should not call or after calling . + > [!NOTE] -> Your implementation of this method for the volatile resource should perform whatever recovery or containment operation it understands on the affected data. It must also call the method on the on the `enlistment` parameter when it has finished its work. - - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. - +> Your implementation of this method for the volatile resource should perform whatever recovery or containment operation it understands on the affected data. It must also call the method on the on the `enlistment` parameter when it has finished its work. + + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + ]]> @@ -227,19 +227,19 @@ A object used to send a response to the transaction manager. Notifies an enlisted object that a transaction is being prepared for commitment. - 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. - - You can also call the method of the `preparingEnlistment` parameter to indicate a vote for rollback. - - If you want the object to merely observe and react to the progress of the transaction, without participating in it, your implementation of this method should call the method of the `preparingEnlistment` parameter when it has finished its work. By doing so, your resource manager would not receive any phase 2 notification. - + 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. + + You can also call the method of the `preparingEnlistment` parameter to indicate a vote for rollback. + + If you want the object to merely observe and react to the progress of the transaction, without participating in it, your implementation of this method should call the method of the `preparingEnlistment` parameter when it has finished its work. By doing so, your resource manager would not receive any phase 2 notification. + ]]> @@ -285,15 +285,15 @@ A object used to send a response to the transaction manager. Notifies an enlisted object that a transaction is being rolled back (aborted). - method on the `enlistment` parameter. - - If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. - + method on the `enlistment` parameter. + + If the resource manager has enlisted durably, but does not respond by calling method, the transaction manager is unsure that the resource manager has received the call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log, which halts the MSDTC process. In the case of a transaction managed by , this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the method once your resource manager is done with your prepare work. + ]]> diff --git a/xml/System.Xml.Schema/XmlSchema.xml b/xml/System.Xml.Schema/XmlSchema.xml index 5489fb8e24a..1bed338bba8 100644 --- a/xml/System.Xml.Schema/XmlSchema.xml +++ b/xml/System.Xml.Schema/XmlSchema.xml @@ -356,7 +356,7 @@ System.Xml.Schema.XmlSchemaDerivationMethod - Gets or sets the attribute which sets the default value of the attribute on element and complex types in the of the schema. + Gets or sets the attribute, which sets the default value of the attribute on element and complex types in the of the schema. An value representing the different methods for preventing derivation. The default value is . System.Xml.Schema.XmlSchemaDerivationMethod - Gets or sets the attribute which sets the default value of the attribute on elements and complex types in the target namespace of the schema. + Gets or sets the attribute, which sets the default value of the attribute on elements and complex types in the target namespace of the schema. An value representing the different methods for preventing derivation. The default value is . Contains a cache of XML Schema definition language (XSD) and XML-Data Reduced (XDR) schemas. The class is obsolete. Use instead. - method, at which time the schema is associated with a namespace Uniform Resource Identifier (URI). For XML Schemas, this will typically be the `targetNamespace` property of the schema. - - Although this class stores both XML Schemas and XDR schemas, any method and property that takes or returns an applies to XML Schemas only. - - This version of the product supports the World Wide Web Consortium (W3C) XML Schema recommendation located at [XML Schema Part 1: Structures](https://www.w3.org/TR/xmlschema-1/) and [XML Schema Part 2: Datatypes](https://www.w3.org/TR/xmlschema-2/). An XML Schema must reference the W3C Schema namespace `http://www.w3.org/2001/XMLSchema` in its schema element. See the method for an example. - - `XmlSchemaCollection` can be used by for efficient data validation. - + method, at which time the schema is associated with a namespace Uniform Resource Identifier (URI). For XML Schemas, this will typically be the `targetNamespace` property of the schema. + + Although this class stores both XML Schemas and XDR schemas, any method and property that takes or returns an applies to XML Schemas only. + + This version of the product supports the World Wide Web Consortium (W3C) XML Schema recommendation located at [XML Schema Part 1: Structures](https://www.w3.org/TR/xmlschema-1/) and [XML Schema Part 2: Datatypes](https://www.w3.org/TR/xmlschema-2/). An XML Schema must reference the W3C Schema namespace `http://www.w3.org/2001/XMLSchema` in its schema element. See the method for an example. + + `XmlSchemaCollection` can be used by for efficient data validation. + > [!IMPORTANT] -> The class is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example validates an XML document using the `XmlSchemaCollection`. - +> The class is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example validates an XML document using the `XmlSchemaCollection`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlSchemaCollection.Basic/CPP/aa.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/Overview/aa.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCollection.Basic/VB/aa.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCollection.Basic/VB/aa.vb" id="Snippet1"::: + ]]> @@ -109,13 +109,13 @@ Initializes a new instance of the class. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -155,13 +155,13 @@ Initializes a new instance of the class. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -216,13 +216,13 @@ Adds the given schema into the schema collection. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -277,23 +277,23 @@ Adds the to the collection. The object. - was always used). - - `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. - - `Semi-trusted code:` External references are not resolved. - + was always used). + + `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. + + `Semi-trusted code:` External references are not resolved. + > [!NOTE] -> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. - +> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. + > [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -341,21 +341,21 @@ The you want to add to this collection. Adds all the namespaces defined in the given collection (including their associated schemas) to this collection. - was always used). - - `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. - - `Semi-trusted code:` External references are not resolved. - + was always used). + + `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. + + `Semi-trusted code:` External references are not resolved. + > [!NOTE] -> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. - +> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. + > [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -417,59 +417,59 @@ Adds the schema located by the given URL into the schema collection. The added to the schema collection; if the schema being added is an XDR schema or if there are compilation errors in the schema. - was always used). - - `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. - - `Semi-trusted code:` External references are not resolved. - + was always used). + + `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. + + `Semi-trusted code:` External references are not resolved. + > [!NOTE] -> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. - +> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. + > [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example validates three XML files using schemas stored in the `XmlSchemaCollection`. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example validates three XML files using schemas stored in the `XmlSchemaCollection`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlValidatingReader/Schemas/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/VB/source.vb" id="Snippet1"::: - - The sample uses the following five input files: - - `booksSchema.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet2"::: - - `booksSchemaFail.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet3"::: - - `newbooks.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet4"::: - - `books.xsd` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet5"::: - - `schema1.xdr` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/VB/source.vb" id="Snippet1"::: + + The sample uses the following five input files: + + `booksSchema.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet2"::: + + `booksSchemaFail.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet3"::: + + `newbooks.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet4"::: + + `books.xsd` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet5"::: + + `schema1.xdr` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlValidatingReader.Schemas Example/XML/source.xml" id="Snippet6"::: + ]]> The schema is not a valid schema. @@ -529,25 +529,25 @@ schemaColl.Add("urn:author", "names.xsd"); Adds the schema contained in the to the schema collection. The added to the schema collection; if the schema being added is an XDR schema or if there are compilation errors in the schema. - was always used). - - `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. - - `Semi-trusted code:` External references are not resolved. - + was always used). + + `Fully trusted code:` A default `XmlUrlResolver` with no user credentials is used to resolve any external resources. The schemas for these other namespaces are loaded for validation purposes only. Unlike the original schema, these other schemas are not explicitly added to the schema collection. As a result, they are not accessible using any of the collection methods or properties. If these external resources are located on a network resource that requires authentication, use an overload that takes an as one of its arguments and specify an `XmlResolver` with the necessary credentials. + + `Semi-trusted code:` External references are not resolved. + > [!NOTE] -> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. - +> If the `XmlSchemaCollection` is being accessed using the property, the `Add` method uses the `XmlResolver` specified by the property. + > [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> The schema is not a valid schema. @@ -606,25 +606,23 @@ schemaColl.Add("urn:author", "names.xsd"); Adds the to the collection. The specified is used to resolve any external references. The added to the schema collection. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example adds a schema to the collection. An is passed to the `Add` method which sets the necessary credentials required to access any external resources referenced in the schema. - +> The class is obsolete and has been replaced by the class. + +## Examples + The following example adds a schema to the collection. An is passed to the `Add` method that sets the necessary credentials required to access any external resources referenced in the schema. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlSchemaCollection.Add/CPP/schemacolladd.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/Add/schemacolladd.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCollection.Add/VB/schemacolladd.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCollection.Add/VB/schemacolladd.vb" id="Snippet1"::: + ]]> The schema is not a valid schema. @@ -689,18 +687,18 @@ schemaColl.Add("urn:author", "names.xsd"); Adds the schema contained in the to the schema collection. The specified is used to resolve any external resources. The added to the schema collection; if the schema being added is an XDR schema or if there are compilation errors in the schema. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> The schema is not a valid schema. @@ -718,13 +716,13 @@ schemaColl.Add("urn:author", "names.xsd"); Gets a value indicating whether a schema with the specified namespace is in the collection. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -774,22 +772,22 @@ schemaColl.Add("urn:author", "names.xsd"); if a schema with the specified namespace is in the collection; otherwise, . - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example checks to see if a schema is in the collection. If it is, it displays the schema. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example checks to see if a schema is in the collection. If it is, it displays the schema. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -838,13 +836,13 @@ schemaColl.Add("urn:author", "names.xsd"); if there is a schema in the collection with the same ; otherwise, . - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -893,13 +891,13 @@ schemaColl.Add("urn:author", "names.xsd"); The index in where copying will begin. Copies all the objects from this collection into the given array starting at the given index. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -946,13 +944,13 @@ schemaColl.Add("urn:author", "names.xsd"); Gets the number of namespaces defined in this collection. The number of namespaces defined in this collection. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -997,22 +995,22 @@ schemaColl.Add("urn:author", "names.xsd"); Provides support for the "for each" style iteration over the collection of schemas. An enumerator for iterating over all schemas in the current collection. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example displays each of the XML Schemas in the schema collection. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example displays each of the XML Schemas in the schema collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlSchemaCollection.GetEnumerator Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/GetEnumerator/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.GetEnumerator Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.GetEnumerator Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1068,22 +1066,22 @@ schemaColl.Add("urn:author", "names.xsd"); Gets the associated with the given namespace URI. The associated with the namespace URI; if there is no loaded schema associated with the given namespace or if the namespace is associated with an XDR schema. - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example checks to see if a schema is in the collection. If it is, it displays the schema. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example checks to see if a schema is in the collection. If it is, it displays the schema. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchemaCollection.this Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1133,13 +1131,13 @@ schemaColl.Add("urn:author", "names.xsd"); Gets the default used by the when loading new schemas. An . - [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + ]]> @@ -1192,11 +1190,11 @@ schemaColl.Add("urn:author", "names.xsd"); The index in where copying will begin. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1242,11 +1240,11 @@ schemaColl.Add("urn:author", "names.xsd"); For a description of this member, see . The count of the items in the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1293,11 +1291,11 @@ schemaColl.Add("urn:author", "names.xsd"); if the collection is synchronized; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1343,11 +1341,11 @@ schemaColl.Add("urn:author", "names.xsd"); For a description of this member, see . A object that can be used to synchronize access to the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1395,11 +1393,11 @@ schemaColl.Add("urn:author", "names.xsd"); For a description of this member, see . The for the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1441,27 +1439,27 @@ schemaColl.Add("urn:author", "names.xsd"); Sets an event handler for receiving information about the XDR and XML schema validation errors. - is thrown on any validation errors where the is `XmlSeverityType.Error`. To specify an event handler, define a callback function and add it to the `ValidationEventHandler`. - + is thrown on any validation errors where the is `XmlSeverityType.Error`. To specify an event handler, define a callback function and add it to the `ValidationEventHandler`. + > [!IMPORTANT] -> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. - - - -## Examples - The following example shows how to set an event handler to handle invalid XML Schemas. - +> The class is obsolete in the .NET Framework version 2.0 and has been replaced by the class. + + + +## Examples + The following example shows how to set an event handler to handle invalid XML Schemas. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlSchema.ValidationEventHandler/CPP/schemaevent.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaCollection/ValidationEventHandler/schemaevent.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchema.ValidationEventHandler/VB/schemaevent.vb" id="Snippet1"::: - - The preceding example uses the file `invalid.xsd` as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchema.ValidationEventHandler/XML/invalid.xsd" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlSchema.ValidationEventHandler/VB/schemaevent.vb" id="Snippet1"::: + + The preceding example uses the file `invalid.xsd` as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlSchema.ValidationEventHandler/XML/invalid.xsd" id="Snippet2"::: + ]]> diff --git a/xml/System.Xml.Schema/XmlSchemaComplexType.xml b/xml/System.Xml.Schema/XmlSchemaComplexType.xml index 3b59bf86e60..d0de2b19018 100644 --- a/xml/System.Xml.Schema/XmlSchemaComplexType.xml +++ b/xml/System.Xml.Schema/XmlSchemaComplexType.xml @@ -51,24 +51,24 @@ Represents the element from XML Schema as specified by the World Wide Web Consortium (W3C). This class defines a complex type that determines the set of attributes and content of an element. - @@ -164,11 +164,11 @@ Gets or sets the value for the component of the complex type. The component of the complex type. - . - + . + ]]> @@ -277,13 +277,13 @@ Gets the collection of all the complied attributes of this complex type and its base types. The collection of all the attributes from this complex type and its base types. The post-compilation value of the property. - @@ -338,11 +338,11 @@ Gets the post-compilation value for for this complex type and its base type(s). The post-compilation value of the element. - @@ -404,22 +404,22 @@ Gets or sets the attribute. The attribute prevents a complex type from being used in the specified type of derivation. The default is . Optional. - @@ -473,22 +473,22 @@ Gets the value after the type has been compiled to the post-schema-validation information set (infoset). This value indicates how the type is enforced when is used in the instance document. The post-schema-validated infoset value. The default is value on the element. - @@ -551,11 +551,11 @@ Gets or sets the post-compilation of this complex type. The content model type that is one of the or classes. - property. - + property. + ]]> @@ -602,29 +602,29 @@ System.Xml.Schema.XmlSchemaContentType - Gets the content model of the complex type which holds the post-compilation value. + Gets the content model of the complex type that holds the post-compilation value. The post-compilation value of the content model for the complex type. - @@ -682,11 +682,11 @@ Gets the particle that holds the post-compilation value of the particle. The particle for the content type. The post-compilation value of the particle. - @@ -792,11 +792,11 @@ , if character data can appear between child elements of this complex type; otherwise, . The default is . Optional. - @@ -867,20 +867,20 @@ Gets or sets the compositor type as one of the , , , or classes. The compositor type. - property. - + property. + ]]> diff --git a/xml/System.Xml.Schema/XmlSchemaSet.xml b/xml/System.Xml.Schema/XmlSchemaSet.xml index e129b53935b..5a25ba996bb 100644 --- a/xml/System.Xml.Schema/XmlSchemaSet.xml +++ b/xml/System.Xml.Schema/XmlSchemaSet.xml @@ -757,7 +757,7 @@ schemaSet.Compile(); are detected by the method; for example, imported schemas. As a result, if a schema for the `http://www.contoso.com/retail` namespace which imports a schema for the `http://www.contoso.com/books` namespace is added to the , calling with `http://www.contoso.com/books` as a parameter, it returns `true`. + Schemas that are indirectly added to the are detected by the method; for example, imported schemas. As a result, if a schema for the `http://www.contoso.com/retail` namespace that imports a schema for the `http://www.contoso.com/books` namespace is added to the , calling with `http://www.contoso.com/books` as a parameter, it returns `true`. ]]> diff --git a/xml/System.Xml.Schema/XmlSchemaType.xml b/xml/System.Xml.Schema/XmlSchemaType.xml index c865b73d404..655ccb5ffc2 100644 --- a/xml/System.Xml.Schema/XmlSchemaType.xml +++ b/xml/System.Xml.Schema/XmlSchemaType.xml @@ -50,11 +50,11 @@ The base class for all simple types and complex types. - class and the class for an example using this class. - + class and the class for an example using this class. + ]]> @@ -154,14 +154,14 @@ Gets the post-compilation object type or the built-in XML Schema Definition Language (XSD) data type, simpleType element, or complexType element. This is a post-schema-compilation infoset property. The built-in XSD data type, simpleType element, or complexType element. - [!IMPORTANT] -> The property is obsolete and has been replaced by the property. - +> The property is obsolete and has been replaced by the property. + ]]> @@ -215,11 +215,11 @@ Gets the post-compilation value for the base type of this schema type. An object representing the base type of this schema type. - property always has a value, because all schema types have a base type. This value is set upon schema compilation, making it a part of the post-schema-compilation infoset. - + property always has a value, because all schema types have a base type. This value is set upon schema compilation, making it a part of the post-schema-compilation infoset. + ]]> @@ -325,20 +325,20 @@ Gets the post-compilation information on how this element was derived from its base type. One of the valid values. - value|Description| -|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -||No derivation method specified.| -||Derived by Substitution.| -||Derived by Extension.| -||Derived by Restriction.| -||Derived by List.| -||Derived by Union.| - + value|Description| +|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +||No derivation method specified.| +||Derived by Substitution.| +||Derived by Extension.| +||Derived by Restriction.| +||Derived by List.| +||Derived by Union.| + ]]> @@ -400,31 +400,31 @@ Gets or sets the final attribute of the type derivation that indicates if further derivations are allowed. One of the valid values. The default is . - value|Description| -|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -||Overrides the schema `blockDefault` setting allowing any derivations by restriction, extension, or substitution to take place.| -||No derivation method is specified. This is the default. Derivation rules are taken from the schema blockDefault setting.| -||Cannot be replaced by a type derived by Substitution.| -||Cannot be replaced by a type derived by Extension.| -||Cannot be replaced by a type derived by Restriction.| -||`#all`. Cannot be replaced by a type derived by any derivation method.| - - The following table shows the values that this property can contain for complex type. - -| value|Description| -|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -||Overrides the schema `blockDefault` setting allowing any derivations by restriction, extension, or substitution to take place.| -||No derivation method is specified. This is the default. Derivation rules are taken from the schema `blockDefault` setting.| -||Cannot be replaced by a type derived by Substitution.| -||Cannot be replaced by a type derived by Extension.| -||Cannot be replaced by a type derived by Restriction.| -||`#all`. Cannot be replaced by a type derived by any derivation method.| - + value|Description| +|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +||Overrides the schema `blockDefault` setting allowing any derivations by restriction, extension, or substitution to take place.| +||No derivation method is specified. This is the default. Derivation rules are taken from the schema blockDefault setting.| +||Cannot be replaced by a type derived by Substitution.| +||Cannot be replaced by a type derived by Extension.| +||Cannot be replaced by a type derived by Restriction.| +||`#all`. Cannot be replaced by a type derived by any derivation method.| + + The following table shows the values that this property can contain for complex type. + +| value|Description| +|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +||Overrides the schema `blockDefault` setting allowing any derivations by restriction, extension, or substitution to take place.| +||No derivation method is specified. This is the default. Derivation rules are taken from the schema `blockDefault` setting.| +||Cannot be replaced by a type derived by Substitution.| +||Cannot be replaced by a type derived by Extension.| +||Cannot be replaced by a type derived by Restriction.| +||`#all`. Cannot be replaced by a type derived by any derivation method.| + ]]> @@ -478,11 +478,11 @@ Gets the post-compilation value of the property. The post-compilation value of the property. The default is the attribute value of the element. - @@ -646,19 +646,17 @@ Returns an that represents the built-in simple type of the specified simple type. The that represents the built-in simple type. - @@ -712,19 +710,17 @@ Returns an that represents the built-in simple type of the simple type that is specified by the qualified name. The that represents the built-in simple type. - The parameter is . @@ -792,33 +788,33 @@ if the derived type is derived from the base type; otherwise, . - method. - -```csharp -XmlSchemaType xsdInteger = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.Integer); -XmlSchemaType xsdPositiveInteger = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.PositiveInteger); - -// true -Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.None)); - -// false -Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.Restriction)); -``` - -```vb -Dim xsdInteger As XmlSchemaType = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.Integer) -Dim xsdPositiveInteger As XmlSchemaType = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.PositiveInteger) - -' True -Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.None)) - -' False -Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.Restriction)) -``` - + method. + +```csharp +XmlSchemaType xsdInteger = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.Integer); +XmlSchemaType xsdPositiveInteger = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.PositiveInteger); + +// true +Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.None)); + +// false +Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.Restriction)); +``` + +```vb +Dim xsdInteger As XmlSchemaType = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.Integer) +Dim xsdPositiveInteger As XmlSchemaType = XmlSchemaType.GetBuiltInSimpleType(XmlTypeCode.PositiveInteger) + +' True +Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.None)) + +' False +Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, XmlSchemaDerivationMethod.Restriction)) +``` + ]]> @@ -869,11 +865,11 @@ Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, Xm if the type has a mixed content model; otherwise, . The default is . - @@ -932,11 +928,11 @@ Console.WriteLine(XmlSchemaType.IsDerivedFrom(xsdPositiveInteger, xsdInteger, Xm Gets or sets the name of the type. The name of the type. - diff --git a/xml/System.Xml.Serialization/XmlAnyElementAttributes.xml b/xml/System.Xml.Serialization/XmlAnyElementAttributes.xml index fdabe0908e4..09668bfef24 100644 --- a/xml/System.Xml.Serialization/XmlAnyElementAttributes.xml +++ b/xml/System.Xml.Serialization/XmlAnyElementAttributes.xml @@ -73,38 +73,38 @@ Represents a collection of objects. - to override the behavior of a set of objects. Multiple instances of the class can be applied to a class member, as long as each instance has a distinct property value; this instructs the to collect unknown elements under the named element into the appropriate array. It is for this reason that multiple instances of the class can be added to the . - - To override a set of objects: - -1. Create an . - -2. Create the set of objects, and add each object to the collection using the method. - -3. Create an . - -4. Set the property to the . - -5. Create an . - -6. Add the to the using the method. - -7. Create an instance of the using the . - -8. Serialize or deserialize an object that contains the set of objects. - - - -## Examples - The following example creates a new and adds it to the collection of objects accessed through the property. The is then added to a which is used to create an . The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named UnknownElements.xml by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. - + to override the behavior of a set of objects. Multiple instances of the class can be applied to a class member, as long as each instance has a distinct property value; this instructs the to collect unknown elements under the named element into the appropriate array. It is for this reason that multiple instances of the class can be added to the . + + To override a set of objects: + +1. Create an . + +2. Create the set of objects, and add each object to the collection using the method. + +3. Create an . + +4. Set the property to the . + +5. Create an . + +6. Add the to the using the method. + +7. Create an instance of the using the . + +8. Serialize or deserialize an object that contains the set of objects. + + + +## Examples + The following example creates a new and adds it to the collection of objects accessed through the property. The is then added to a , which is used to create an . The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named UnknownElements.xml by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/CPP/xmlanyover.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAnyElementAttributes/Overview/xmlanyover.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: + ]]> @@ -204,15 +204,15 @@ Adds an to the collection. The index of the newly added . - and adds it to the collection of objects accessed through the property. The is then added to an , which is used to create an . The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named UnknownElements.xml by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. - + and adds it to the collection of objects accessed through the property. The is then added to an , which is used to create an . The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named UnknownElements.xml by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/CPP/xmlanyover.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAnyElementAttributes/Overview/xmlanyover.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml.Serialization/XmlAttributeOverrides.xml b/xml/System.Xml.Serialization/XmlAttributeOverrides.xml index b2bd20b9859..5ade2b5dacd 100644 --- a/xml/System.Xml.Serialization/XmlAttributeOverrides.xml +++ b/xml/System.Xml.Serialization/XmlAttributeOverrides.xml @@ -57,38 +57,38 @@ Allows you to override property, field, and class attributes when you use the to serialize or deserialize an object. - enables the to override the default way of serializing a set of objects. Overriding serialization in this way has two uses: first, you can control and augment the serialization of objects found in a DLL--even if you do not have access to the source; second, you can create one set of serializable classes, but serialize the objects in multiple ways. For example, instead of serializing members of a class instance as XML elements, you can serialize them as XML attributes, resulting in a more efficient document to transport. - - After you create an object, you pass it as an argument to the constructor. The resulting uses the data contained by the to override attributes that control how objects are serialized. To accomplish this, the contains a collection of the object types that are overridden, as well as an object associated with each overridden object type. The object itself contains an appropriate set of attribute objects that control how each field, property, or class is serialized. - - The process for creating and using an object is as follows: - -1. Create an object. - -2. Create an attribute object that is appropriate to the object being overridden. For example, to override a field or property, create an , using the new, derived type. You can optionally assign a new , or that overrides the base class's attribute name or namespace. - -3. Add the attribute object to the appropriate property or collection. For example, you would add the to the collection of the object, specifying the member name that is being overridden. - -4. Create an object. - -5. Using the method, add the object to the object. If the object being overridden is an or , you need only to specify the type of the overridden object. But if you are overriding a field or property, you must also specify the name of the overridden member. - -6. When constructing the , pass the to the constructor. - -7. Use the resulting to serialize or deserialize the derived class objects. - - - -## Examples - The following example serializes a class named `Orchestra`, which contains a single field named `Instruments` that returns an array of `Instrument` objects. A second class named `Brass` inherits from the `Instrument` class. The example uses an instance of the class to override the `Instrument` field, allowing the field to accept `Brass` objects. - + enables the to override the default way of serializing a set of objects. Overriding serialization in this way has two uses: first, you can control and augment the serialization of objects found in a DLL--even if you do not have access to the source; second, you can create one set of serializable classes, but serialize the objects in multiple ways. For example, instead of serializing members of a class instance as XML elements, you can serialize them as XML attributes, resulting in a more efficient document to transport. + + After you create an object, you pass it as an argument to the constructor. The resulting uses the data contained by the to override attributes that control how objects are serialized. To accomplish this, the contains a collection of the object types that are overridden, as well as an object associated with each overridden object type. The object itself contains an appropriate set of attribute objects that control how each field, property, or class is serialized. + + The process for creating and using an object is as follows: + +1. Create an object. + +2. Create an attribute object that is appropriate to the object being overridden. For example, to override a field or property, create an , using the new, derived type. You can optionally assign a new , or that overrides the base class's attribute name or namespace. + +3. Add the attribute object to the appropriate property or collection. For example, you would add the to the collection of the object, specifying the member name that is being overridden. + +4. Create an object. + +5. Using the method, add the object to the object. If the object being overridden is an or , you need only to specify the type of the overridden object. But if you are overriding a field or property, you must also specify the name of the overridden member. + +6. When constructing the , pass the to the constructor. + +7. Use the resulting to serialize or deserialize the derived class objects. + + + +## Examples + The following example serializes a class named `Orchestra`, which contains a single field named `Instruments` that returns an array of `Instrument` objects. A second class named `Brass` inherits from the `Instrument` class. The example uses an instance of the class to override the `Instrument` field, allowing the field to accept `Brass` objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeOverrides Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeOverrides/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -201,22 +201,22 @@ An object that represents the overriding attributes. Adds an object to the collection of objects. The parameter specifies an object to be overridden by the object. - object contains a union of attribute objects that cause the to override its default serialization behavior for a set of objects. You choose the attribute objects to place in the object, depending on the particular behaviors you want to override. For example, the serializes a class member as an XML element by default. If you want the member to be serialized as an XM attribute instead, you would create an , assign it to the property of an , and add the object to the object. - - Use this overload to override an or . - - - -## Examples - The following example serializes a class named `Band` which is derived from a class named `Orchestra`. The example creates an object, and assigns it to the property of an object. The example then calls the method to add the object to the object. - + object contains a union of attribute objects that cause the to override its default serialization behavior for a set of objects. You choose the attribute objects to place in the object, depending on the particular behaviors you want to override. For example, the serializes a class member as an XML element by default. If you want the member to be serialized as an XM attribute instead, you would create an , assign it to the property of an , and add the object to the object. + + Use this overload to override an or . + + + +## Examples + The following example serializes a class named `Band`, which is derived from a class named `Orchestra`. The example creates an object, and assigns it to the property of an object. The example then calls the method to add the object to the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeOverrides/Add/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -281,22 +281,22 @@ An object that represents the overriding attributes. Adds an object to the collection of objects. The parameter specifies an object to be overridden. The parameter specifies the name of a member that is overridden. - object contains a union of attribute objects that cause the to override its default serialization behavior for a set of objects. You choose the attribute objects to place in the object, depending on the particular behaviors you want to override. For example, the serializes a class member as an XML element by default. If you want the member to be serialized as an XML attribute instead, you would create an , assign it to the property of an , and add the object to the object. - - Use this method when attempting to override an , , , , or . - - - -## Examples - The following example creates an object, and assigns it to the property of an object. The example then adds the object to an object, before creating an . - + object contains a union of attribute objects that cause the to override its default serialization behavior for a set of objects. You choose the attribute objects to place in the object, depending on the particular behaviors you want to override. For example, the serializes a class member as an XML element by default. If you want the member to be serialized as an XML attribute instead, you would create an , assign it to the property of an , and add the object to the object. + + Use this method when attempting to override an , , , , or . + + + +## Examples + The following example creates an object, and assigns it to the property of an object. The example then adds the object to an object, before creating an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeOverrides/Add/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.Add1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -367,22 +367,22 @@ Gets the object associated with the specified, base-class, type. An that represents the collection of overriding attributes. - object that contains attributes for an or object. - - If the object contains objects that override an , , , , or , you must use the overload that specifies the overridden member as well as the type. - - - -## Examples - The following example creates an object, an object, and an object. The example assigns the to the property of the object, and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class to the object. In this example, the is `Group`. - + object that contains attributes for an or object. + + If the object contains objects that override an , , , , or , you must use the overload that specifies the overridden member as well as the type. + + + +## Examples + The following example creates an object, an object, and an object. The example assigns the to the property of the object, and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class to the object. In this example, the is `Group`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeOverrides/Item/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -445,20 +445,20 @@ Gets the object associated with the specified (base-class) type. The member parameter specifies the base-class member that is overridden. An that represents the collection of overriding attributes. - object that contains objects that override an , , , , or . If the object contains an or , you must use the overload that specifies only the overridden type. - - - -## Examples - The following example creates an object, an , and an object. The example assigns the to the property of the object and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class and member name to the object. - + object that contains objects that override an , , , , or . If the object contains an or , you must use the overload that specifies only the overridden type. + + + +## Examples + The following example creates an object, an , and an object. The example assigns the to the property of the object and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class and member name to the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributeOverrides/Item/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributeOverrides.this1 Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml.Serialization/XmlAttributes.xml b/xml/System.Xml.Serialization/XmlAttributes.xml index 2ce511de282..81bf60a3266 100644 --- a/xml/System.Xml.Serialization/XmlAttributes.xml +++ b/xml/System.Xml.Serialization/XmlAttributes.xml @@ -60,7 +60,7 @@ is part of a process that overrides the default way the serializes class instances. For example, suppose you want to serialize an object that is created from a DLL which has an inaccessible source. By using the , you can augment or otherwise control how the object is serialized. + Creating the is part of a process that overrides the default way the serializes class instances. For example, suppose you want to serialize an object that is created from a DLL that has an inaccessible source. By using the , you can augment or otherwise control how the object is serialized. The members of the class correspond directly to a family of attribute classes that control serialization. For example, the property must be set to an , which allows you to override serialization of a field or property by instructing the to serialize the property value as XML text. For a complete list of attributes that control serialization, see the . diff --git a/xml/System.Xml.Serialization/XmlSerializationWriter.xml b/xml/System.Xml.Serialization/XmlSerializationWriter.xml index b056d5dc114..778cfdb6a00 100644 --- a/xml/System.Xml.Serialization/XmlSerializationWriter.xml +++ b/xml/System.Xml.Serialization/XmlSerializationWriter.xml @@ -56,13 +56,13 @@ Represents an abstract class used for controlling serialization by the class. - class. is also implemented within the .NET Framework for serialization of and objects into XML documents. - - You should not derive classes from . Instead, call the method. - + class. is also implemented within the .NET Framework for serialization of and objects into XML documents. + + You should not derive classes from . Instead, call the method. + ]]> @@ -164,17 +164,17 @@ An instance of the delegate. Stores an implementation of the delegate and the type it applies to, for a later invocation. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - During initialization, the .NET Framework XML serialization infrastructure dynamically generates and compiles a temporary class for serialization that is derived from . During this process, the .NET Framework generates write methods that implement the delegate. It does so for certain mappings between .NET Framework types and XML data types that are serialized via SOAP-encoded XML and are not root elements. Then, as necessary, a write method is called during serialization. - - You should not directly create an instance of . - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + During initialization, the .NET Framework XML serialization infrastructure dynamically generates and compiles a temporary class for serialization that is derived from . During this process, the .NET Framework generates write methods that implement the delegate. It does so for certain mappings between .NET Framework types and XML data types that are serialized via SOAP-encoded XML and are not root elements. Then, as necessary, a write method is called during serialization. + + You should not directly create an instance of . + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -229,11 +229,11 @@ Creates an that indicates an unexpected name for an element that adheres to an XML Schema element declaration. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -288,7 +288,7 @@ The object that represents the invalid member. - Creates an that indicates the which has been invalidly applied to a member; only members that are of type , or derived from , are valid. + Creates an that indicates the that has been invalidly applied to a member; only members that are of type , or derived from , are valid. The newly created exception. To be added. @@ -333,7 +333,7 @@ The that is invalid. - Creates an that indicates the which has been invalidly applied to a member; only members that are of type , or derived from , are valid. + Creates an that indicates the that has been invalidly applied to a member; only members that are of type , or derived from , are valid. The newly created exception. To be added. @@ -384,11 +384,11 @@ Creates an that indicates a failure while writing an array where an XML Schema element declaration is applied. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -488,11 +488,11 @@ Creates an that indicates that a value for an XML element does not match an enumeration type. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -543,11 +543,11 @@ Creates an that indicates that an XML element that should adhere to the XML Schema element declaration cannot be processed. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -612,11 +612,11 @@ Creates an that indicates that a type being serialized is not being used in a valid manner or is unexpectedly encountered. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -671,11 +671,11 @@ Creates an that indicates that a type being serialized is not being used in a valid manner or is unexpectedly encountered. The newly created exception. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -730,11 +730,11 @@ if the method returns an encoded name; otherwise, . - method writes valid XML from invalid sources. For example, the property of the class can contain spaces, which are invalid as XML. The method reads the encoded XML and restores it to the original value. However, the method of the cannot read such encoded XML. In that case, set the property to `false` to disable the encoding of the XML. - + method writes valid XML from invalid sources. For example, the property of the class can contain spaces, which are invalid as XML. The method reads the encoded XML and restores it to the original value. However, the method of the cannot read such encoded XML. In that case, set the property to `false` to disable the encoding of the XML. + ]]> @@ -783,13 +783,13 @@ Processes a base-64 byte array. The same byte array that was passed in as an argument. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - Rather than return a string as other similar "from" methods, the static method returns the original `byte[]` object to improve performance and conserve memory. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + Rather than return a string as other similar "from" methods, the static method returns the original `byte[]` object to improve performance and conserve memory. + ]]> @@ -845,13 +845,13 @@ Produces a string from an input hexadecimal byte array. The byte array value converted to a string. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -900,13 +900,13 @@ Produces a string from an input . The value converted to a string. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -955,13 +955,13 @@ Produces a string from a object. A string representation of the that shows the date but no time. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1010,13 +1010,13 @@ Produces a string from an input . A string representation of the that shows the date and time. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1031,11 +1031,11 @@ Takes a numeric enumeration value and returns a string that consists of delimited identifiers that represent the enumeration members that have been set. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1087,13 +1087,13 @@ Produces a string that consists of delimited identifiers that represent the enumeration members that have been set. A string that consists of delimited identifiers, where each represents a member from the set enumerator list. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1147,11 +1147,11 @@ Takes a numeric enumeration value and the names and constants from the enumerator list for the enumeration and returns a string that consists of delimited identifiers that represent the enumeration members that have been set. A string that consists of delimited identifiers, where each item is one of the values set by the bitwise operation. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1200,13 +1200,13 @@ Produces a string from a object. A string representation of the object that shows the time but no date. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1262,13 +1262,13 @@ Encodes a valid XML name by replacing characters that are not valid with escape sequences. An encoded string. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1324,13 +1324,13 @@ Encodes a valid XML local name by replacing characters that are not valid with escape sequences. An encoded string. - class are intended for use by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + class are intended for use by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1386,13 +1386,13 @@ Encodes an XML name. An encoded string. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1448,13 +1448,13 @@ Encodes a space-delimited sequence of XML names into a single XML name. An encoded string. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1520,11 +1520,11 @@ Returns an XML qualified name, with invalid characters replaced by escape sequences. An XML qualified name, with invalid characters replaced by escape sequences. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1624,19 +1624,19 @@ Initializes an instances of the delegate to serialize SOAP-encoded XML data. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - During initialization, the .NET Framework XML serialization infrastructure dynamically generates and compiles a temporary class for serialization that is derived from . During this process, the .NET Framework generates write methods that implement the delegate. It does so for certain mappings between .NET Framework types and XML data types that are serialized using SOAP-encoded XML and are not root elements. Then, as necessary, a write method is called during serialization. - - The abstract method is where the temporary derived class creates an instance of and initializes write callback methods. - - You should not directly create an instance of . - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + During initialization, the .NET Framework XML serialization infrastructure dynamically generates and compiles a temporary class for serialization that is derived from . During this process, the .NET Framework generates write methods that implement the delegate. It does so for certain mappings between .NET Framework types and XML data types that are serialized using SOAP-encoded XML and are not root elements. Then, as necessary, a write method is called during serialization. + + The abstract method is where the temporary derived class creates an instance of and initializes write callback methods. + + You should not directly create an instance of . + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -1682,11 +1682,11 @@ Gets or sets a list of XML qualified name objects that contain the namespaces and prefixes used to produce qualified names in XML documents. An that contains the namespaces and prefix pairs. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1741,13 +1741,13 @@ Gets a dynamically generated assembly by name. A dynamically generated assembly. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is static. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is static. + ]]> @@ -1792,15 +1792,15 @@ Initializes object references only while serializing a SOAP-encoded SOAP message. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element and to be referenced any number of times by substitute elements. The method helps keep track of the objects that can be serialized as `multiRef` elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element and to be referenced any number of times by substitute elements. The method helps keep track of the objects that can be serialized as `multiRef` elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -1868,11 +1868,11 @@ The value of the XML attribute as a byte array. Instructs an object to write an XML attribute that has no namespace specified for its name. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1930,11 +1930,11 @@ The value of the XML attribute as a string. Instructs the to write an XML attribute that has no namespace specified for its name. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -1994,11 +1994,11 @@ The value of the XML attribute as a byte array. Instructs an object to write an XML attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2058,11 +2058,11 @@ The value of the XML attribute as a string. Writes an XML attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2124,11 +2124,11 @@ The value of the XML attribute as a string. Writes an XML attribute where the namespace prefix is provided manually. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2194,13 +2194,13 @@ to indicate that the node, if an XML element, adheres to an XML Schema element declaration; otherwise, . Writes an XML node object within the body of a named XML element. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -2266,13 +2266,13 @@ to indicate that the node, if an XML element, adheres to an XML Schema element declaration; otherwise, . Instructs an object to write an object within the body of a named XML element. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -2346,11 +2346,11 @@ The name to write, using its prefix if namespace-qualified, in the element text. Writes an XML element with a specified qualified name in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2416,11 +2416,11 @@ The name to write, using its prefix if namespace-qualified, in the element text. Writes an XML element with a specified qualified name in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2486,11 +2486,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified qualified name in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2552,11 +2552,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified qualified name in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2630,11 +2630,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2700,11 +2700,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2770,11 +2770,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2836,11 +2836,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2914,11 +2914,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -2982,11 +2982,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3052,11 +3052,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3122,11 +3122,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3192,11 +3192,11 @@ The text value of the XML element. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3262,11 +3262,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3328,11 +3328,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3394,11 +3394,11 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element with a specified value in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3463,11 +3463,11 @@ The local name of the XML element to write. Writes an XML element whose body is empty. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3518,11 +3518,11 @@ The namespace of the XML element to write. Writes an XML element whose body is empty. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3577,11 +3577,11 @@ Writes a element tag. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3630,11 +3630,11 @@ The object being serialized. Writes a element tag. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3688,15 +3688,15 @@ The object being serialized. Writes an attribute that appears in a SOAP-encoded element. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times by `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times by `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -3745,11 +3745,11 @@ The XML namespaces to declare. Writes the namespace declaration attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -3811,15 +3811,15 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element whose body contains a valid XML qualified name. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -3879,15 +3879,15 @@ The XML qualified name to write in the body of the XML element. Writes an XML element whose body contains a valid XML qualified name. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -3949,15 +3949,15 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element that contains a string as the body. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4029,15 +4029,15 @@ The name of the XML Schema data type to be written to the attribute. Writes a byte array as the body of an XML element. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4099,15 +4099,15 @@ The name of the XML Schema data type to be written to the attribute. Writes an XML element that contains a string as the body. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4167,15 +4167,15 @@ The string to write in the body of the XML element. Writes an XML element that contains a string as the body. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -4245,15 +4245,15 @@ The byte array to write in the body of the XML element. Writes a byte array as the body of an XML element. inserts an attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -4313,15 +4313,15 @@ The string to write in the body of the XML element. Writes an XML element that contains a string as the body. inserts a attribute if the string's value is . - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -4386,15 +4386,15 @@ The local name of the XML element to write. Writes an XML element with an attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4445,15 +4445,15 @@ The namespace of the XML element to write. Writes an XML element with an attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing SOAP-encoded XML, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4518,15 +4518,15 @@ The local name of the XML element to write. Writes an XML element with an attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -4577,15 +4577,15 @@ The namespace of the XML element to write. Writes an XML element with an attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. - - The method is called only when writing literal XML that can be defined in an XML Schema document. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + When set to `true`, the `nil` attribute from the XML Schema instance namespace (abbreviated `xsi`) indicates a null value. + + The method is called only when writing literal XML that can be defined in an XML Schema document. + ]]> @@ -4658,15 +4658,15 @@ The object being serialized either in the current XML element or a element that is referenced by the current element. Writes a SOAP message XML element that can contain a reference to a XML element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4731,15 +4731,15 @@ The type stored in the object's type mapping (as opposed to the object's type found directly through the operation). Writes a SOAP message XML element that can contain a reference to a XML element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4814,15 +4814,15 @@ to serialize the object directly into the XML element rather than make the element reference another element that contains the data; otherwise, . Writes a SOAP message XML element that can contain a reference to a XML element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4889,15 +4889,15 @@ to write an attribute if the object to serialize is ; otherwise, . Writes a SOAP message XML element that can contain a reference to a XML element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -4956,11 +4956,11 @@ Gets or sets the that is being used by the . The used by the class instance. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5011,15 +5011,15 @@ Serializes objects into SOAP-encoded XML elements in a SOAP message. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -5095,15 +5095,15 @@ The object being serialized. Writes a SOAP message XML element that contains a reference to a element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -5166,15 +5166,15 @@ to write an attribute if the object to serialize is ; otherwise, . Writes a SOAP message XML element that contains a reference to a element for a given object. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. - - SOAP encoding is described in Section 5 of the SOAP 1.1 specification. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + SOAP encoding allows a unique XML element to appear once within a SOAP message as a `multiRef` element identified by an `id` attribute. The `id` value can be referenced multiple times using `href` attributes (or `ref` attributes in SOAP 1.2) in substitute elements. + + SOAP encoding is described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -5232,13 +5232,13 @@ The namespace of the result body. Writes a SOAP 1.2 RPC result element with a specified qualified name in its body. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The `result` element is defined in the namespace "http://www.w3.org/2002/12/soap-rpc". - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The `result` element is defined in the namespace "http://www.w3.org/2002/12/soap-rpc". + ]]> @@ -5317,11 +5317,11 @@ to write an attribute if the class object is ; otherwise, . Writes an object that uses custom XML formatting as an XML element. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5428,11 +5428,11 @@ Writes the XML declaration if the writer is positioned at the start of an XML document. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5496,11 +5496,11 @@ The local name of the XML element to write. Writes an opening element tag, including any attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5564,11 +5564,11 @@ The namespace of the XML element to write. Writes an opening element tag, including any attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5635,11 +5635,11 @@ to write the element name with a prefix if none is available for the specified namespace; otherwise, . Writes an opening element tag, including any attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5705,11 +5705,11 @@ The object being serialized as an XML element. Writes an opening element tag, including any attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5778,11 +5778,11 @@ to write the element name with a prefix if none is available for the specified namespace; otherwise, . Writes an opening element tag, including any attributes. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -5912,13 +5912,13 @@ if the XML element explicitly specifies the text value's type using the attribute; otherwise, . Writes an XML element whose text body is a value of a simple XML Schema data type. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The `xsi:type` attribute explicitly indicates the XML Schema data type. The prefix `xsi` refers to the XML Schema instance namespace. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The `xsi:type` attribute explicitly indicates the XML Schema data type. The prefix `xsi` refers to the XML Schema instance namespace. + ]]> @@ -5977,11 +5977,11 @@ The byte array to write. Writes a base-64 byte array. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -6030,11 +6030,11 @@ The value of the string to write. Writes a specified string value. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -6098,11 +6098,11 @@ The XML node to write. Writes the specified as an XML attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -6160,11 +6160,11 @@ An object (or ) used to generate a qualified name value for an attribute from the Web Services Description Language (WSDL) namespace ("http://schemas.xmlsoap.org/wsdl/"). Writes the specified object as an XML attribute. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + ]]> @@ -6222,13 +6222,13 @@ The namespace of an XML Schema data type. Writes an attribute for an XML element that is being serialized into a document. - are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. - - The `xsi:type` attribute explicitly indicates the XML Schema data type. The prefix `xsi` refers to the XML Schema instance namespace. - + are intended for use only by derived classes that are used internally within the .NET Framework XML serialization infrastructure. + + The `xsi:type` attribute explicitly indicates the XML Schema data type. The prefix `xsi` refers to the XML Schema instance namespace. + ]]> diff --git a/xml/System.Xml.XPath/XPathNamespaceScope.xml b/xml/System.Xml.XPath/XPathNamespaceScope.xml index 7cf8452a802..2fc3d8e425c 100644 --- a/xml/System.Xml.XPath/XPathNamespaceScope.xml +++ b/xml/System.Xml.XPath/XPathNamespaceScope.xml @@ -56,11 +56,11 @@ Defines the namespace scope. - enumeration can be passed to the and methods of the class to specify the type of namespace node to move to. - + enumeration can be passed to the and methods of the class to specify the type of namespace node to move to. + ]]> @@ -106,7 +106,7 @@ 0 - Returns all namespaces defined in the scope of the current node. This includes the xmlns:xml namespace which is always declared implicitly. The order of the namespaces returned is not defined. + Returns all namespaces defined in the scope of the current node. This includes the xmlns:xml namespace, which is always declared implicitly. The order of the namespaces returned is not defined. diff --git a/xml/System.Xml.XPath/XPathNavigator.xml b/xml/System.Xml.XPath/XPathNavigator.xml index 9ddd6273b58..f9e40496339 100644 --- a/xml/System.Xml.XPath/XPathNavigator.xml +++ b/xml/System.Xml.XPath/XPathNavigator.xml @@ -89,64 +89,64 @@ Provides a cursor model for navigating and editing XML data. - class in the namespace is an abstract class which defines a cursor model for navigating and editing XML information items as instances of the XQuery 1.0 and XPath 2.0 Data Model. - - An object is created from a class that implements the interface such as the and classes. objects created by objects are read-only while objects created by objects can be edited. An object's read-only or editable status is determined using the property of the class. - - For more information about processing XML data using the XPath data model, see the [Process XML Data Using the XPath Data Model](/dotnet/standard/data/xml/process-xml-data-using-the-xpath-data-model) topic. - + class in the namespace is an abstract class which defines a cursor model for navigating and editing XML information items as instances of the XQuery 1.0 and XPath 2.0 Data Model. + + An object is created from a class that implements the interface such as the and classes. objects created by objects are read-only while objects created by objects can be edited. An object's read-only or editable status is determined using the property of the class. + + For more information about processing XML data using the XPath data model, see the [Process XML Data Using the XPath Data Model](/dotnet/standard/data/xml/process-xml-data-using-the-xpath-data-model) topic. + > [!IMPORTANT] -> Exceptions raised as a result of using the class, such as the class, may contain sensitive information that should not be exposed in untrusted scenarios. Exceptions should be properly handled so that this sensitive information is not exposed in untrusted scenarios. - +> Exceptions raised as a result of using the class, such as the class, may contain sensitive information that should not be exposed in untrusted scenarios. Exceptions should be properly handled so that this sensitive information is not exposed in untrusted scenarios. + ]]> - When you inherit from the class, you must override the following members: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- + When you inherit from the class, you must override the following members: + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- @@ -200,11 +200,11 @@ Initializes a new instance of the class. - @@ -261,63 +261,63 @@ Returns an object used to create one or more new child nodes at the end of the list of child nodes of the current node. An object used to create new child nodes at the end of the list of child nodes of the current node. - method. - -- The new child node is not inserted until the method of the object is called. - -- The method is valid only when the is positioned on the root node or an element node. - -- The method does not affect the position of the . - - You can write more than one node to the writer. All nodes are appended to the end of the list of child nodes of the current node. - - - -## Examples - In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. - + method. + +- The new child node is not inserted until the method of the object is called. + +- The method is valid only when the is positioned on the root node or an element node. + +- The method does not affect the position of the . + + You can write more than one node to the writer. All nodes are appended to the end of the list of child nodes of the current node. + + + +## Examples + In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet1"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet1"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The current node the is positioned on is not the root node or an element node. @@ -369,61 +369,61 @@ The XML data string for the new child node. Creates a new child node at the end of the list of child nodes of the current node using the XML data string specified. - ")`. The string for appending the text "book" to the current node's text node is `AppendChild("book")`. If the XML string contains multiple nodes, all nodes are added. - - The following are important notes to consider when using the method. - -- The method is valid only when the is positioned on the root node or an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file. - + ")`. The string for appending the text "book" to the current node's text node is `AppendChild("book")`. If the XML string contains multiple nodes, all nodes are added. + + The following are important notes to consider when using the method. + +- The method is valid only when the is positioned on the root node or an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet2"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet2"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XML data string parameter is . @@ -477,61 +477,61 @@ An object positioned on the XML data for the new child node. Creates a new child node at the end of the list of child nodes of the current node using the XML contents of the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on the root node or an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is appended using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on the root node or an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is appended using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet3"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet3"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object is in an error state or closed. @@ -586,61 +586,61 @@ An object positioned on the node to add as the new child node. Creates a new child node at the end of the list of child nodes of the current node using the nodes in the specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on the root node or an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the node contained in the specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is appended using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on the root node or an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file using the node contained in the specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is appended using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet4"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet4"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object parameter is . @@ -707,69 +707,69 @@ The value of the new child element node. If or are passed, an empty element is created. Creates a new child element node at the end of the list of child nodes of the current node using the namespace prefix, local name and namespace URI specified with the value specified. - method or the method. For example, the following syntax appends a child element by using the in-scope namespace `xmlns:bk=http://www.contoso.com/books`: - -```csharp -navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) -``` - - This creates the new child `` element. - - The following are important notes to consider when using the method. - -- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. - -- The method is valid only when the is positioned on the root node or an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file. - + method or the method. For example, the following syntax appends a child element by using the in-scope namespace `xmlns:bk=http://www.contoso.com/books`: + +```csharp +navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) +``` + + This creates the new child `` element. + + The following are important notes to consider when using the method. + +- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. + +- The method is valid only when the is positioned on the root node or an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet5"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet5"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The current node the is positioned on is not the root node or an element node. @@ -819,16 +819,16 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig When overridden in a derived class, gets the base URI for the current node. The location from which the node was loaded, or if there is no value. - property tells you where these nodes originate from. - - For example, if the XML data is loaded from `http://server/mydata.xml`, the property returns `http://server/mydata.xml`. - + property tells you where these nodes originate from. + + For example, if the XML data is loaded from `http://server/mydata.xml`, the property returns `http://server/mydata.xml`. + > [!NOTE] -> Nodes created using the class have the same as the XML document the was created from. - +> Nodes created using the class have the same as the XML document the was created from. + ]]> @@ -876,58 +876,58 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig if the can edit the underlying XML data; otherwise, . - property has different values based on the three different implementations of the interface in .NET. The values for objects created by each implementation are listed in the following table. - -| Implementation| Value| -|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`false`| -||`true`| - - - -## Examples - The following example uses the property to display the values of the and classes. - + property has different values based on the three different implementations of the interface in .NET. The values for objects created by each implementation are listed in the following table. + +| Implementation| Value| +|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| +||`false`| +||`true`| + + + +## Examples + The following example uses the property to display the values of the and classes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet1"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet1"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -980,20 +980,20 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig if no schema validation errors occurred; otherwise, . - method verifies that the XML data contained in the conforms to a global type or declaration in the schema or schemas provided in the . - -- The method does not perform infoset augmentation. This means that schema defaults are not applied, text values are not converted to atomic values, and no new type information is associated with information items. - -- Schema `xsi:schemaLocation` or `xsi:noNamespaceSchemaLocation` hints in the XML data of are ignored. - -- If the is positioned on a document node, the validation process includes checking of uniqueness and reference constraints (`xs:ID`, `xs:IDREF`, `xs:key`, `xs:keyref`, and `xs:unique`). Otherwise, these checks are omitted. - -- If the passed as a parameter is `null` and the is positioned on an element node, the type information exposed by the property's property is used to check the node's validity. If the passed as a parameter is `null` and the is positioned on the root node, the property of the document element (that is, the element child of the root node) is used. In both cases if the property of the element's property is `null` and the passed as a parameter is `null`, an is thrown because there is no type information to use to perform validation. - + method verifies that the XML data contained in the conforms to a global type or declaration in the schema or schemas provided in the . + +- The method does not perform infoset augmentation. This means that schema defaults are not applied, text values are not converted to atomic values, and no new type information is associated with information items. + +- Schema `xsi:schemaLocation` or `xsi:noNamespaceSchemaLocation` hints in the XML data of are ignored. + +- If the is positioned on a document node, the validation process includes checking of uniqueness and reference constraints (`xs:ID`, `xs:IDREF`, `xs:key`, `xs:keyref`, and `xs:unique`). Otherwise, these checks are omitted. + +- If the passed as a parameter is `null` and the is positioned on an element node, the type information exposed by the property's property is used to check the node's validity. If the passed as a parameter is `null` and the is positioned on the root node, the property of the document element (that is, the element child of the root node) is used. In both cases if the property of the element's property is `null` and the passed as a parameter is `null`, an is thrown because there is no type information to use to perform validation. + ]]> A schema validation error occurred, and no was specified to handle validation errors. @@ -1045,54 +1045,54 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig When overridden in a derived class, creates a new positioned at the same node as this . A new positioned at the same node as this . - method is especially useful in conjunction with the . An is used to iterate over a selected node set, and contains a property which returns an positioned on the context node of the . However, the returned by the property cannot be used to move away from the node set. Instead, you clone the returned and use the cloned navigator to do any additional moves. - - The cloned is not affected by subsequent changes to the original . - - - -## Examples - The following example gets all book titles authored by Herman Melville. - + method is especially useful in conjunction with the . An is used to iterate over a selected node set, and contains a property which returns an positioned on the context node of the . However, the returned by the property cannot be used to move away from the node set. Instead, you clone the returned and use the cloned navigator to do any additional moves. + + The cloned is not affected by subsequent changes to the original . + + + +## Examples + The following example gets all book titles authored by Herman Melville. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet6"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet6"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -1145,34 +1145,34 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig Compares the position of the current with the position of the specified. An value representing the comparative position of the two objects. - enumeration. - -|XmlNodeOrder|Description| -|------------------|-----------------| -||The current node of this is before the current node of the supplied .| -||The current node of this is after the current node of the supplied .| -||The two objects are positioned on the same node.| -||The node positions cannot be determined relative to each other in the document order, or `null` is specified as the parameter. This could occur if the two nodes reside in different trees.| - - The method's behavior is dependent on the the is currently positioned on. When comparing nodes in the XML document, the following rules apply: - -- nodes: These nodes are returned in document order from the source document. - -- nodes: These nodes may be returned in document order and are always before the nodes of the parent element. - -- nodes: These nodes may be returned in document order. They always come after the nodes and before any child nodes of the parent node. - + enumeration. + +|XmlNodeOrder|Description| +|------------------|-----------------| +||The current node of this is before the current node of the supplied .| +||The current node of this is after the current node of the supplied .| +||The two objects are positioned on the same node.| +||The node positions cannot be determined relative to each other in the document order, or `null` is specified as the parameter. This could occur if the two nodes reside in different trees.| + + The method's behavior is dependent on the the is currently positioned on. When comparing nodes in the XML document, the following rules apply: + +- nodes: These nodes are returned in document order from the source document. + +- nodes: These nodes may be returned in document order and are always before the nodes of the parent element. + +- nodes: These nodes may be returned in document order. They always come after the nodes and before any child nodes of the parent node. + > [!NOTE] > For more information about the XPath data model and details about each of the node types, see section 5 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - - This method has no effect on the state of the . - + + This method has no effect on the state of the . + > [!NOTE] -> Use the method rather than the method when possible. - +> Use the method rather than the method when possible. + ]]> @@ -1225,21 +1225,21 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig Compiles a string representing an XPath expression and returns an object. An object representing the XPath expression. - and methods. Expressions that return a Boolean, number, or string can be used in the method. The rules on valid expressions for the method are specific to that method. - + and methods. Expressions that return a Boolean, number, or string can be used in the method. The rules on valid expressions for the method are specific to that method. + ]]> The parameter contains an XPath expression that is not valid. @@ -1300,72 +1300,70 @@ navigator.AppendChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navig The namespace prefix of the new attribute node (if any). - The local name of the new attribute node which cannot or . + The local name of the new attribute node, which can't be or . The namespace URI for the new attribute node (if any). The value of the new attribute node. If or are passed, an empty attribute node is created. Creates an attribute node on the current element node using the namespace prefix, local name and namespace URI specified with the value specified. - or method. For example, the following syntax creates an attribute by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: - -```csharp -editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(navigator.Prefix), "text") -``` - - This creates the new attribute `` on the current element. - - The following are important notes to consider when using the method. - -- If the namespace prefix specified is or `null`, the prefix for the namespace URI of the new attribute is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, a namespace prefix is automatically generated. For example to create a new attribute on an element in the default namespace of the `contosoBooks.xml` file, (`xmlns="http://www.contoso.com/books"`), you specify `null` or for both the namespace prefix and namespace URI parameters. Specifying `http://www.contoso.com/books` as the namespace URI parameter will cause the method to auto generate a namespace prefix for the new attribute. - -- If the new attribute created is a namespace node which conflicts with a namespace declaration on the element, either because the namespace prefix chosen is used by another namespace declaration at the same scope, or because the prefix chosen is the same as that of the element but is bound to a different namespace URI, an exception is thrown. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `discount` attribute is created on the `price` child element of the first `book` element in the `contosoBooks.xml` file. - + or method. For example, the following syntax creates an attribute by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: + +```csharp +editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(navigator.Prefix), "text") +``` + + This creates the new attribute `` on the current element. + + The following are important notes to consider when using the method. + +- If the namespace prefix specified is or `null`, the prefix for the namespace URI of the new attribute is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, a namespace prefix is automatically generated. For example to create a new attribute on an element in the default namespace of the `contosoBooks.xml` file, (`xmlns="http://www.contoso.com/books"`), you specify `null` or for both the namespace prefix and namespace URI parameters. Specifying `http://www.contoso.com/books` as the namespace URI parameter will cause the method to auto generate a namespace prefix for the new attribute. + +- If the new attribute created is a namespace node that conflicts with a namespace declaration on the element, either because the namespace prefix chosen is used by another namespace declaration at the same scope, or because the prefix chosen is the same as that of the element but is bound to a different namespace URI, an exception is thrown. + +- The method does not affect the position of the . + +## Examples + In the following example, a new `discount` attribute is created on the `price` child element of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet7"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet7"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The is not positioned on an element node. @@ -1415,65 +1413,65 @@ editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(naviga Returns an object used to create new attributes on the current element. An object used to create new attributes on the current element. - method. - -- When the is positioned on an element, the new attributes created by the method are placed at the end of the attribute list of the current element. - -- The new attributes are not inserted until the method of the object is called. - -- If the namespace prefix specified is or `null`, the prefix for the namespace URI of the new attribute is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, a namespace prefix is automatically generated. For example to create a new attribute on an element in the default namespace of the `contosoBooks.xml` file, (`xmlns="http://www.contoso.com/books"`), you specify `null` or for both the namespace prefix and namespace URI parameters. Specifying `http://www.contoso.com/books` as the namespace URI parameter will cause the method to auto generate a namespace prefix for the new attribute. - -- If the new attribute created is a namespace node which conflicts with a namespace declaration on the element, either because the namespace prefix chosen is used by another namespace declaration at the same scope, or because the prefix chosen is the same as that of the element but is bound to a different namespace URI, an exception is thrown. - -- The object returned may only be used to create attributes. Calling other object methods that do not create attributes throws an exception. - -- The method does not affect the position of the . - - - -## Examples - In the following example, new `discount` and `currency` attributes are created on the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. - + method. + +- When the is positioned on an element, the new attributes created by the method are placed at the end of the attribute list of the current element. + +- The new attributes are not inserted until the method of the object is called. + +- If the namespace prefix specified is or `null`, the prefix for the namespace URI of the new attribute is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, a namespace prefix is automatically generated. For example to create a new attribute on an element in the default namespace of the `contosoBooks.xml` file, (`xmlns="http://www.contoso.com/books"`), you specify `null` or for both the namespace prefix and namespace URI parameters. Specifying `http://www.contoso.com/books` as the namespace URI parameter will cause the method to auto generate a namespace prefix for the new attribute. + +- If the new attribute created is a namespace node that conflicts with a namespace declaration on the element, either because the namespace prefix chosen is used by another namespace declaration at the same scope, or because the prefix chosen is the same as that of the element but is bound to a different namespace URI, an exception is thrown. + +- The object returned may only be used to create attributes. Calling other object methods that do not create attributes throws an exception. + +- The method does not affect the position of the . + + + +## Examples + In the following example, new `discount` and `currency` attributes are created on the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet8"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet8"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The is not positioned on an element node. @@ -1532,11 +1530,11 @@ editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(naviga Returns a copy of the . An copy of this . - method. - + method. + ]]> @@ -1586,53 +1584,53 @@ editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(naviga An positioned on the last sibling node in the range to delete. Deletes a range of sibling nodes from the current node to the node specified. - method deletes a range of sibling nodes from the current node the is positioned on (inclusive) to the node specified by the parameter (inclusive). The is then positioned on its parent node. - - - -## Examples - In the following example, the first and second `book` elements of the `contosoBooks.xml` file are deleted using the method. - + method deletes a range of sibling nodes from the current node the is positioned on (inclusive) to the node specified by the parameter (inclusive). The is then positioned on its parent node. + + + +## Examples + In the following example, the first and second `book` elements of the `contosoBooks.xml` file are deleted using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet52"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet52"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet52"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet52"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The specified is . @@ -1688,58 +1686,58 @@ editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(naviga Deletes the current node and its child nodes. - is positioned on the deleted node's parent node on successful deletion. - -- If the deleted node is a text node which is the content of a simple typed element, the element loses its type information. This means that when positioned on the element the , and properties have the values `null`, and respectively. - -- Deleted nodes are still accessible to objects positioned over them prior to deletion. However methods that attempt to move away from the deleted sub-tree fail. For example, the and methods always fail when the is positioned over the top most deleted node. This is because the deleted node is no longer connected to the XML document. Similarly the method always fails if the is positioned on the bottom-most deleted node. - - - -## Examples - In the following example the `price` element of the first `book` element of the `contosoBooks.xml` file is deleted using the method. The position of the object after the `price` element is deleted is on the parent `book` element. - + is positioned on the deleted node's parent node on successful deletion. + +- If the deleted node is a text node that is the content of a simple typed element, the element loses its type information. This means that when positioned on the element the , and properties have the values `null`, and respectively. + +- Deleted nodes are still accessible to objects positioned over them prior to deletion. However methods that attempt to move away from the deleted sub-tree fail. For example, the and methods always fail when the is positioned over the top most deleted node. This is because the deleted node is no longer connected to the XML document. Similarly the method always fails if the is positioned on the bottom-most deleted node. + + + +## Examples + In the following example the `price` element of the first `book` element of the `contosoBooks.xml` file is deleted using the method. The position of the object after the `price` element is deleted is on the parent `book` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet9"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet9"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The is positioned on a node that cannot be deleted such as the root node or a namespace node. @@ -1802,62 +1800,62 @@ editor.CreateAttribute(navigator.Prefix, "attributeName", LookupNamespace(naviga Evaluates the specified XPath expression and returns the typed result. The result of the expression (Boolean, number, string, or node set). This maps to , , , or objects respectively. - [!NOTE] -> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload which takes an as an argument; otherwise, position() and last() return 0. - - This method has no effect on the state of the . - - - -## Examples - The following example evaluates an XPath expression and returns a . - +> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload that takes an as an argument; otherwise, position() and last() return 0. + + This method has no effect on the state of the . + + + +## Examples + The following example evaluates an XPath expression and returns a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet10"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet10"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The return type of the XPath expression is a node set. @@ -1920,63 +1918,61 @@ nav.Evaluate("Price/text()*10"); Evaluates the and returns the typed result. The result of the expression (Boolean, number, string, or node set). This maps to , , , or objects respectively. - [!NOTE] -> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload which takes an as an argument; otherwise, position() and last() return 0. - - This method has no effect on the state of the . - - - -## Examples - The following example evaluates an and returns a . - +> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload that takes an as an argument; otherwise, position() and last() return 0. + + This method has no effect on the state of the . + +## Examples + The following example evaluates an and returns a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet11"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet11"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The return type of the XPath expression is a node set. @@ -2041,63 +2037,63 @@ nav.Evaluate(expr); Evaluates the specified XPath expression and returns the typed result, using the object specified to resolve namespace prefixes in the XPath expression. The result of the expression (Boolean, number, string, or node set). This maps to , , , or objects respectively. - [!NOTE] -> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload which takes an as an argument; otherwise, position() and last() return 0. - - This method has no effect on the state of the . - - - -## Examples - The following example evaluates an XPath expression and returns a using the object specified to resolve namespace prefixes in the XPath expression. - +> The XPath position() and last() functions, unless used as a predicate in a location step, require a reference to a node set in order to be evaluated. In this case, you must use the overload that takes an as an argument; otherwise, position() and last() return 0. + + This method has no effect on the state of the . + + + +## Examples + The following example evaluates an XPath expression and returns a using the object specified to resolve namespace prefixes in the XPath expression. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet12"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet12"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The return type of the XPath expression is a node set. @@ -2161,63 +2157,63 @@ nav.Evaluate(expr); Uses the supplied context to evaluate the , and returns the typed result. The result of the expression (Boolean, number, string, or node set). This maps to , , , or objects respectively. - node of the as the context node. If `context` is `null`, the node on which the is currently positioned is used as the context node. - - The position() and last() functions, unless used as a predicate in a location step, always return 0 under the following conditions: - -- The `context` argument is `null`. - -- has not been called on the . - - Because the position() and last() functions work on the current node, you should not use the property to move away from the selected node set. This could invalidate the state of the . - - This method has no effect on the state of the . - - - -## Examples - The following example evaluates an and returns a using the node of the as the context node. - + node of the as the context node. If `context` is `null`, the node on which the is currently positioned is used as the context node. + + The position() and last() functions, unless used as a predicate in a location step, always return 0 under the following conditions: + +- The `context` argument is `null`. + +- has not been called on the . + + Because the position() and last() functions work on the current node, you should not use the property to move away from the selected node set. This could invalidate the state of the . + + This method has no effect on the state of the . + + + +## Examples + The following example evaluates an and returns a using the node of the as the context node. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet13"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet13"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The return type of the XPath expression is a node set. @@ -2277,13 +2273,13 @@ nav.Evaluate(expr); Gets the value of the attribute with the specified local name and namespace URI. A that contains the value of the specified attribute; if a matching attribute is not found, or if the is not positioned on an element node. - must be positioned on an element node before calling the method. - - This method has no effect on the state of the . - + must be positioned on an element node before calling the method. + + This method has no effect on the state of the . + ]]> @@ -2343,15 +2339,15 @@ nav.Evaluate(expr); Returns the value of the namespace node corresponding to the specified local name. A that contains the value of the namespace node; if a matching namespace node is not found, or if the is not positioned on an element node. - is specified as the `name` parameter, the method returns the default `xmlns` namespace. - + is specified as the `name` parameter, the method returns the default `xmlns` namespace. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - - This method does not affect the state of the . - + + This method does not affect the state of the . + ]]> @@ -2408,17 +2404,17 @@ nav.Evaluate(expr); Returns the in-scope namespaces of the current node. An collection of namespace names keyed by prefix. - value specified. - -|XmlNamespaceScope Value|Namespaces Returned| -|-----------------------------|-------------------------| -||All namespaces defined in the scope of the current node. This includes the `xmlns:xml` namespace, which is always declared implicitly. The order of the namespaces returned is not defined.| -||All namespaces defined in the scope of the current node, excluding the `xmlns:xml` namespace, which is always declared implicitly. The order of the namespaces returned is not defined.| -||All namespaces that are defined locally at the current node.| - + value specified. + +|XmlNamespaceScope Value|Namespaces Returned| +|-----------------------------|-------------------------| +||All namespaces defined in the scope of the current node. This includes the `xmlns:xml` namespace, which is always declared implicitly. The order of the namespaces returned is not defined.| +||All namespaces defined in the scope of the current node, excluding the `xmlns:xml` namespace, which is always declared implicitly. The order of the namespaces returned is not defined.| +||All namespaces that are defined locally at the current node.| + ]]> @@ -2523,19 +2519,19 @@ nav.Evaluate(expr); if the current node has any child nodes; otherwise, . - is positioned on a node that cannot have child nodes, the property always returns `false`. - - The following table lists the child node nodes allowed for each node. - -|XPathNodeType Node|Child XPathNodeType Nodes| -|------------------------|-------------------------------| -||, , or nodes. **Note:** is equivalent to when using the class and can have the same children as an element.| -||, , , , or nodes.| -|All other nodes|Cannot have child nodes.| - + is positioned on a node that cannot have child nodes, the property always returns `false`. + + The following table lists the child node nodes allowed for each node. + +|XPathNodeType Node|Child XPathNodeType Nodes| +|------------------------|-------------------------------| +||, , or nodes. **Note:** is equivalent to when using the class and can have the same children as an element.| +||, , , , or nodes.| +|All other nodes|Cannot have child nodes.| + ]]> @@ -2585,55 +2581,55 @@ nav.Evaluate(expr); Gets or sets the markup representing the child nodes of the current node. A that contains the markup of the child nodes of the current node. - [!NOTE] -> The and properties are not very efficient. If performance is a priority, it is more efficient to use the node navigation methods of the to get values of child nodes. - - - -## Examples - The following example uses the property to display the contents of the first `book` element in the `contosoBooks.xml` file and its child nodes in the . - +> The and properties are not very efficient. If performance is a priority, it is more efficient to use the node navigation methods of the to get values of child nodes. + + + +## Examples + The following example uses the property to display the contents of the first `book` element in the `contosoBooks.xml` file and its child nodes in the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet2"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet2"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The property cannot be set. @@ -2691,59 +2687,59 @@ nav.Evaluate(expr); Returns an object used to create a new sibling node after the currently selected node. An object used to create a new sibling node after the currently selected node. - method. - -- The new sibling node is not inserted until the method of the object is called. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned by the method. - + method. + +- The new sibling node is not inserted until the method of the object is called. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned by the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet14"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet14"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The position of the does not allow a new sibling node to be inserted after the current node. @@ -2795,59 +2791,59 @@ nav.Evaluate(expr); The XML data string for the new sibling node. Creates a new sibling node after the currently selected node using the XML string specified. - ")`. The string for inserting the text "book" after the current node's text node is `InsertAfter("book")`. If the XML string contains multiple nodes, all nodes are added. - - The following are important notes to consider when using the method. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file. - + ")`. The string for inserting the text "book" after the current node's text node is `InsertAfter("book")`. If the XML string contains multiple nodes, all nodes are added. + + The following are important notes to consider when using the method. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet15"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet15"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XML string parameter is . @@ -2901,59 +2897,59 @@ nav.Evaluate(expr); An object positioned on the XML data for the new sibling node. Creates a new sibling node after the currently selected node using the XML contents of the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet16"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet16"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object is in an error state or closed. @@ -3008,59 +3004,59 @@ nav.Evaluate(expr); An object positioned on the node to add as the new sibling node. Creates a new sibling node after the currently selected node using the nodes in the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet17"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet17"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object parameter is . @@ -3120,59 +3116,59 @@ nav.Evaluate(expr); Returns an object used to create a new sibling node before the currently selected node. An object used to create a new sibling node before the currently selected node. - method. - -- The new sibling node is not inserted until the method of the object is called. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned by the method. - + method. + +- The new sibling node is not inserted until the method of the object is called. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned by the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet18"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet18"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet18"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The position of the does not allow a new sibling node to be inserted before the current node. @@ -3224,59 +3220,59 @@ nav.Evaluate(expr); The XML data string for the new sibling node. Creates a new sibling node before the currently selected node using the XML string specified. - ")`. The string for inserting the text "book" before the current node's text node is `InsertBefore("book")`. If the XML string contains multiple nodes, all nodes are added. - - The following are important notes to consider when using the method. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file. - + ")`. The string for inserting the text "book" before the current node's text node is `InsertBefore("book")`. If the XML string contains multiple nodes, all nodes are added. + + The following are important notes to consider when using the method. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet19"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet19"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet19"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XML string parameter is . @@ -3330,59 +3326,59 @@ nav.Evaluate(expr); An object positioned on the XML data for the new sibling node. Creates a new sibling node before the currently selected node using the XML contents of the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet20"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet20"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object is in an error state or closed. @@ -3437,59 +3433,59 @@ nav.Evaluate(expr); An object positioned on the node to add as the new sibling node. Creates a new sibling node before the currently selected node using the nodes in the specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new sibling element is inserted using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet21"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet21"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object parameter is . @@ -3556,67 +3552,67 @@ nav.Evaluate(expr); The value of the new child element. If or are passed, an empty element is created. Creates a new sibling element after the current node using the namespace prefix, local name and namespace URI specified, with the value specified. - or method. For example, the following syntax inserts a sibling element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: - -```csharp -navigator.InsertElementAfter(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) -``` - - This creates the new sibling `` element. - - The following are important notes to consider when using the method. - -- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file. - + or method. For example, the following syntax inserts a sibling element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: + +```csharp +navigator.InsertElementAfter(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) +``` + + This creates the new sibling `` element. + + The following are important notes to consider when using the method. + +- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted after the `price` child element of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet22"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet22"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet22"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The position of the does not allow a new sibling node to be inserted after the current node. @@ -3682,67 +3678,67 @@ navigator.InsertElementAfter(navigator.Prefix, "pages", LookupNamespaceURI(navig The value of the new child element. If or are passed, an empty element is created. Creates a new sibling element before the current node using the namespace prefix, local name, and namespace URI specified, with the value specified. - or method. For example, the following syntax inserts a sibling element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: - -```csharp -navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) -``` - - This creates the new sibling `` element. - - The following are important notes to consider when using the method. - -- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- The method does not affect the position of the . - - - -## Examples - In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file. - + or method. For example, the following syntax inserts a sibling element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: + +```csharp +navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) +``` + + This creates the new sibling `` element. + + The following are important notes to consider when using the method. + +- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- The method does not affect the position of the . + + + +## Examples + In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet23"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet23"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The position of the does not allow a new sibling node to be inserted before the current node. @@ -3805,21 +3801,21 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the specified is a descendant of the current ; otherwise, . - is a descendant of the current if it is positioned on a descendant node of the current . Take, for example, the following XML string: - - `widget` - - If the current is positioned on the `item` node, and the specified is positioned on the `name` node, returns `true`. - - This method always returns `false` under the following conditions: - -- The specified shares the same implementation but points at a different document instance than the current navigator. - -- The specified has a different implementation than the current navigator. - + is a descendant of the current if it is positioned on a descendant node of the current . Take, for example, the following XML string: + + `widget` + + If the current is positioned on the `item` node, and the specified is positioned on the `name` node, returns `true`. + + This method always returns `false` under the following conditions: + +- The specified shares the same implementation but points at a different document instance than the current navigator. + +- The specified has a different implementation than the current navigator. + ]]> @@ -3868,17 +3864,17 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the current node is an empty element; otherwise, . - `|`true`| -|`test`|`false`| -|``|`false`| - + `|`true`| +|`test`|`false`| +|``|`false`| + ]]> @@ -3975,17 +3971,17 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the two objects have the same position; otherwise, . - method assumes that the specified shares the same implementation and is points at the same document instance as the current . - - This method always returns `false` under the following conditions: - -- The specified shares the same implementation but points at a different document instance than the current . - -- The has a different implementation than the current . - + method assumes that the specified shares the same implementation and is points at the same document instance as the current . + + This method always returns `false` under the following conditions: + +- The specified shares the same implementation but points at a different document instance than the current . + +- The has a different implementation than the current . + ]]> @@ -4034,63 +4030,63 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the of the current node without any namespace prefix. A that contains the local name of the current node, or if the current node does not have a name (for example, text or comment nodes). - of the current node. For example, the local name for the `` element is `book`. - - The following table lists the value returned by the property, based on the of the current node. - -|XPathNodeType|Property Value| -|-------------------|--------------------| -||The local name of the element.| -||The local name of the attribute.| -||The prefix associated with the namespace URI.| -||The target of the processing instruction.| -|All other nodes|.| - - - -## Examples - The following example iterates over the node tree recursively, and displays information about and nodes. - + of the current node. For example, the local name for the `` element is `book`. + + The following table lists the value returned by the property, based on the of the current node. + +|XPathNodeType|Property Value| +|-------------------|--------------------| +||The local name of the element.| +||The local name of the attribute.| +||The prefix associated with the namespace URI.| +||The target of the processing instruction.| +|All other nodes|.| + + + +## Examples + The following example iterates over the node tree recursively, and displays information about and nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -4153,19 +4149,19 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Gets the namespace URI for the specified prefix. A that contains the namespace URI assigned to the namespace prefix specified; if no namespace URI is assigned to the prefix specified. The returned is atomized. - is specified as the `prefix` parameter, the currently assigned default namespace URI is returned. If no default namespace URI is explicitly assigned, and is specified as the `prefix` parameter, the blank prefix is associated with elements that are not in any namespace, and is returned. - + is specified as the `prefix` parameter, the currently assigned default namespace URI is returned. If no default namespace URI is explicitly assigned, and is specified as the `prefix` parameter, the blank prefix is associated with elements that are not in any namespace, and is returned. + > [!NOTE] -> The prefix to namespace URI mappings can change from node to node in an XML document. As a result, the value of the method may not be consistent from one node to the next. - - - -## Examples - For an example of the method, see the or methods. - +> The prefix to namespace URI mappings can change from node to node in an XML document. As a result, the value of the method may not be consistent from one node to the next. + + + +## Examples + For an example of the method, see the or methods. + ]]> @@ -4226,14 +4222,14 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Gets the prefix declared for the specified namespace URI. A that contains the namespace prefix assigned to the namespace URI specified; otherwise, if no prefix is assigned to the namespace URI specified. The returned is atomized. - method returns the first prefix that matches the namespace URI specified. Multiple prefixes referring to the same namespace URI are not ordered in any particular way, so a particular prefix may not be returned each time when more than one is assigned. - + method returns the first prefix that matches the namespace URI specified. Multiple prefixes referring to the same namespace URI are not ordered in any particular way, so a particular prefix may not be returned each time when more than one is assigned. + > [!NOTE] -> Namespace URI to prefix mappings can change from node to node in an XML document. As a result, the value of the method may not be consistent from one node to the next. - +> Namespace URI to prefix mappings can change from node to node in an XML document. As a result, the value of the method may not be consistent from one node to the next. + ]]> @@ -4295,16 +4291,16 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the current node matches the specified XPath expression; otherwise, . - . - - - -## Examples - For an example of the method, see the method. - + . + + + +## Examples + For an example of the method, see the method. + ]]> The XPath expression cannot be evaluated. @@ -4359,53 +4355,53 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the current node matches the ; otherwise, . - . This method is identical to the method, except that a object containing the compiled XPath expression is specified, rather than an XPath expression . - - - -## Examples - The following example displays the titles of all novels. - + . This method is identical to the method, except that a object containing the compiled XPath expression is specified, rather than an XPath expression . + + + +## Examples + The following example displays the titles of all novels. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet24"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet24"::: - - The example uses the file, `books.xml`, as input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet24"::: + + The example uses the file, `books.xml`, as input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XPath expression cannot be evaluated. @@ -4460,13 +4456,13 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the same position as the specified ; otherwise, . If , the position of the is unchanged. - specified is an that shares the same implementation and points at the same document instance as the current . - - This method always returns `false` if the specified is an that has a different implementation than the current . - + specified is an that shares the same implementation and points at the same document instance as the current . + + This method always returns `false` if the specified is an that has a different implementation than the current . + ]]> @@ -4525,15 +4521,15 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the attribute; otherwise, . If , the position of the is unchanged. - is not currently positioned on an element, this method returns `false`. - - After a successful call to , the , and properties reflect the values of the attribute. When the is positioned on an attribute, the methods , , and are not applicable. These methods always return `false` and do not change the position of the navigator. Rather, you can call to move to the next attribute node. - - Once positioned on an attribute, you can call to move to the owner element. - + is not currently positioned on an element, this method returns `false`. + + After a successful call to , the , and properties reflect the values of the attribute. When the is positioned on an attribute, the methods , , and are not applicable. These methods always return `false` and do not change the position of the navigator. Rather, you can call to move to the next attribute node. + + Once positioned on an attribute, you can call to move to the owner element. + ]]> @@ -4597,19 +4593,19 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the child node; otherwise, . If , the position of the is unchanged. - method depends on the of the current node, and the of the child node to move to. - - The following table shows the different nodes, and the child nodes they can move to. - -|Current Node's XPathNodeType|Child Node's XPathNodeType| -|----------------------------------|--------------------------------| -||, , , or .| -||, , , or .| -|All other values|None.| - + method depends on the of the current node, and the of the child node to move to. + + The following table shows the different nodes, and the child nodes they can move to. + +|Current Node's XPathNodeType|Child Node's XPathNodeType| +|----------------------------------|--------------------------------| +||, , , or .| +||, , , or .| +|All other values|None.| + ]]> @@ -4663,11 +4659,11 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the child node; otherwise, . If , the position of the is unchanged. - method, see the method. - + method, see the method. + ]]> @@ -4719,8 +4715,8 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Moves the to the first sibling node of the current node. - if the is successful moving to the first sibling node of the current node; if there is no first sibling, or if the is currently positioned on an attribute node. If the is already positioned on the first sibling, will return and will not move its position. - + if the is successful moving to the first sibling node of the current node; if there is no first sibling, or if the is currently positioned on an attribute node. If the is already positioned on the first sibling, will return and will not move its position. + If returns because there is no first sibling, or if is currently positioned on an attribute, the position of the is unchanged. To be added. @@ -4772,57 +4768,57 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the first attribute of the current node; otherwise, . If , the position of the is unchanged. - is not currently positioned on an element, this method returns `false` and the position of the does not change. - - After a successful call to , the , and properties reflect the values of the attribute. When the is positioned on an attribute, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next attribute node. - - After the is positioned on an attribute, you can call to move to the owner element. - - - -## Examples - The following example uses the and methods to display all the attributes for each book in the `books.xml` file. - + is not currently positioned on an element, this method returns `false` and the position of the does not change. + + After a successful call to , the , and properties reflect the values of the attribute. When the is positioned on an attribute, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next attribute node. + + After the is positioned on an attribute, you can call to move to the owner element. + + + +## Examples + The following example uses the and methods to display all the attributes for each book in the `books.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet49"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet49"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet49"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet49"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -4876,16 +4872,16 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the first child node of the current node; otherwise, . If , the position of the is unchanged. - and are the only two values that can have children. This property always returns `false` for all other node types. - - - -## Examples - For an example of the method, see the method. - + and are the only two values that can have children. This property always returns `false` for all other node types. + + + +## Examples + For an example of the method, see the method. + ]]> @@ -4954,19 +4950,19 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the first namespace node; otherwise, . If , the position of the is unchanged. - class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. - - After the has been moved to the namespace node, the property reflects the name of the namespace. - - When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. - - After the is positioned on an namespace node, call to move back to the element node. - + class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. + + After the has been moved to the namespace node, the property reflects the name of the namespace. + + When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. + + After the is positioned on an namespace node, call to move back to the element node. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - + ]]> @@ -5022,35 +5018,35 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the first namespace node; otherwise, . If , the position of the is unchanged. - class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. - - Using the following XML fragment as an example, if the is positioned on the `data` node, behaves in the following manner. - -- `MoveToFirstNamespace(XPathNamespaceScope.All)` moves to one of the following namespace nodes: `xmlns:c='C'`, `xmlns:a='A2'`, `xmlns=''`, `xmlns:b='B'`, or `xmlns:xml='http://www.w3.org/XML/1998/namespace'`. - -- `MoveToFirstNamespace(XPathNamespaceScope.ExcludeXml)` moves to one of the following namespace nodes: `xmlns:c='C'`, `xmlns:a='A2'`, `xmlns=''`, or `xmlns:b='B'`. - -- `MoveToFirstNamespace(XPathNamespaceScope.Local)` moves to the `xmlns:c='C'` node. - -```xml - - - - - -``` - - If the is not currently positioned on an element, this method returns `false` and the position of the does not change. After the has been moved to the namespace node, the property reflects the name of the namespace. - - When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. - - After the is positioned on an namespace node, call to move back to the element node. - + class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. + + Using the following XML fragment as an example, if the is positioned on the `data` node, behaves in the following manner. + +- `MoveToFirstNamespace(XPathNamespaceScope.All)` moves to one of the following namespace nodes: `xmlns:c='C'`, `xmlns:a='A2'`, `xmlns=''`, `xmlns:b='B'`, or `xmlns:xml='http://www.w3.org/XML/1998/namespace'`. + +- `MoveToFirstNamespace(XPathNamespaceScope.ExcludeXml)` moves to one of the following namespace nodes: `xmlns:c='C'`, `xmlns:a='A2'`, `xmlns=''`, or `xmlns:b='B'`. + +- `MoveToFirstNamespace(XPathNamespaceScope.Local)` moves to the `xmlns:c='C'` node. + +```xml + + + + + +``` + + If the is not currently positioned on an element, this method returns `false` and the position of the does not change. After the has been moved to the namespace node, the property reflects the name of the namespace. + + When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. + + After the is positioned on an namespace node, call to move back to the element node. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - + ]]> @@ -5120,56 +5116,56 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the moved successfully; otherwise, . - method does not move to attribute or namespace nodes. If the parameter value is or , the method returns `false` and the position of the is unchanged. - -- If the method returns `false`, the position of the is unchanged. - - - -## Examples - In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `bookstore` element. - + method does not move to attribute or namespace nodes. If the parameter value is or , the method returns `false` and the position of the is unchanged. + +- If the method returns `false`, the position of the is unchanged. + + + +## Examples + In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `bookstore` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet25"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet25"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet25"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -5229,53 +5225,53 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the moved successfully; otherwise, . - method returns `false`, the position of the is unchanged. - - - -## Examples - In the following example, the is moved from the root of the `contosoBooks.xml` file to the first `price` element. - + method returns `false`, the position of the is unchanged. + + + +## Examples + In the following example, the is moved from the root of the `contosoBooks.xml` file to the first `price` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet26"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet26"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet26"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet26"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -5330,62 +5326,62 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the moved successfully; otherwise, . - method does not move to attribute or namespace nodes. If the parameter value is or , the method returns `false` and the position of the is unchanged. - -- If the boundary passed as a parameter is not positioned after the position of the current it is ignored. - -- If boundary passed as a parameter is `null` the next following node with the specified is located in document order. - -- The methods cannot be used to move to attribute or namespace nodes. If the boundary passed as a parameter is positioned over an attribute or namespace node, it is equivalent to the boundary parameter having been positioned on the first child node of its parent element. This ensures that the parent element of the attribute or namespace node that the boundary parameter is positioned on can be matched by this method. - -- If the method returns `false`, the position of the is unchanged. - - - -## Examples - In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `price` element. A clone of the object is made using the method. The cloned , positioned on the `price` element, will be used as a boundary. Changes in the position of the cloned do not affect the original . The original is moved back to the root of the `contosoBooks.xml` file using the method. The title and first and last name of the author are retrieved using the method and an of . The method will return true until the `price` element boundary is reached. - + method does not move to attribute or namespace nodes. If the parameter value is or , the method returns `false` and the position of the is unchanged. + +- If the boundary passed as a parameter is not positioned after the position of the current it is ignored. + +- If boundary passed as a parameter is `null` the next following node with the specified is located in document order. + +- The methods cannot be used to move to attribute or namespace nodes. If the boundary passed as a parameter is positioned over an attribute or namespace node, it is equivalent to the boundary parameter having been positioned on the first child node of its parent element. This ensures that the parent element of the attribute or namespace node that the boundary parameter is positioned on can be matched by this method. + +- If the method returns `false`, the position of the is unchanged. + + + +## Examples + In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `price` element. A clone of the object is made using the method. The cloned , positioned on the `price` element, will be used as a boundary. Changes in the position of the cloned do not affect the original . The original is moved back to the root of the `contosoBooks.xml` file using the method. The title and first and last name of the author are retrieved using the method and an of . The method will return true until the `price` element boundary is reached. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet27"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet27"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet27"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet27"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -5449,60 +5445,60 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the moved successfully; otherwise, . - boundary passed as a parameter is not positioned after the position of the current it is ignored. - -- If the boundary parameter is `null`, the following element with the local name and namespace URI specified is located in document order. - -- The methods cannot be used to move to attribute or namespace nodes. If the boundary passed as a parameter is positioned over an attribute or namespace node, it is equivalent to the boundary parameter having been positioned on the first child node of its parent element. This ensures that the parent element of the attribute or namespace node that the boundary parameter is positioned on can be matched by this method. - -- If the method returns `false`, the position of the is unchanged. - - - -## Examples - In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `book` element. A clone of the object is made using the method and is moved from the `book` element to the following `first-name` element. The cloned , positioned on the `first-name` element, will be used as a boundary. Changes in the position of the cloned do not affect the original . The original then attempts to move to the following `price` element using the method with the boundary passed as a parameter. This move fails because the following `price` element is beyond the boundary. The original then attempts to move to the following `title` element which is before the boundary using the same method and succeeds. - + boundary passed as a parameter is not positioned after the position of the current it is ignored. + +- If the boundary parameter is `null`, the following element with the local name and namespace URI specified is located in document order. + +- The methods cannot be used to move to attribute or namespace nodes. If the boundary passed as a parameter is positioned over an attribute or namespace node, it is equivalent to the boundary parameter having been positioned on the first child node of its parent element. This ensures that the parent element of the attribute or namespace node that the boundary parameter is positioned on can be matched by this method. + +- If the method returns `false`, the position of the is unchanged. + + + +## Examples + In the following example, the is moved from the root of the `contosoBooks.xml` file to the following `book` element. A clone of the object is made using the method and is moved from the `book` element to the following `first-name` element. The cloned , positioned on the `first-name` element, will be used as a boundary. Changes in the position of the cloned do not affect the original . The original then attempts to move to the following `price` element using the method with the boundary passed as a parameter. This move fails because the following `price` element is beyond the boundary. The original then attempts to move to the following `title` element which is before the boundary using the same method and succeeds. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet28"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet28"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet28"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -5555,15 +5551,15 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving; otherwise, . If , the position of the navigator is unchanged. - `, was loaded using a DTD that included the following: ``. - - If the was positioned somewhere in the XML data, calling `MoveToId("a1")` positions the on the element node `x`. - + `, was loaded using a DTD that included the following: ``. + + If the was positioned somewhere in the XML data, calling `MoveToId("a1")` positions the on the element node `x`. + ]]> @@ -5620,17 +5616,17 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the specified namespace; if a matching namespace node was not found, or if the is not positioned on an element node. If , the position of the is unchanged. - has been moved to the namespace node, the property reflects the name of the namespace. - - When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. - - After the is positioned on a namespace node, you can call to move back to the element node. - + has been moved to the namespace node, the property reflects the name of the namespace. + + When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . Rather, you can call to move to the next namespace node. + + After the is positioned on a namespace node, you can call to move back to the element node. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - + ]]> @@ -5692,48 +5688,48 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the next sibling node; otherwise, if there are no more siblings or if the is currently positioned on an attribute node. If , the position of the is unchanged. - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -5787,21 +5783,21 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the next sibling node; otherwise, if there are no more siblings or if the is currently positioned on an attribute node. If , the position of the is unchanged. - method depends on the of the current node and the of the next sibling node to move to. - - The following table shows the different nodes and the sibling nodes they can move to. - -|Current Node's XPathNodeType|Sibling Node's XPathNodeType| -|----------------------------------|----------------------------------| -||, , , or .| -||, , , or .| -||, , , or .| -||, , , or .| -|All other values|None.| - + method depends on the of the current node and the of the next sibling node to move to. + + The following table shows the different nodes and the sibling nodes they can move to. + +|Current Node's XPathNodeType|Sibling Node's XPathNodeType| +|----------------------------------|----------------------------------| +||, , , or .| +||, , , or .| +||, , , or .| +||, , , or .| +|All other values|None.| + ]]> @@ -5902,57 +5898,57 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the next attribute; if there are no more attributes. If , the position of the is unchanged. - is not currently positioned on an attribute, this method returns `false` and the position of the does not change. - - When the is positioned on an attribute, the methods , , and methods are not applicable. These methods always return `false` and do not change the position of the . - - After the is positioned on an attribute, you can call to move to the owner element. - - - -## Examples - The following example uses the and methods to display all the attributes for each book in the `books.xml` file. - + is not currently positioned on an attribute, this method returns `false` and the position of the does not change. + + When the is positioned on an attribute, the methods , , and methods are not applicable. These methods always return `false` and do not change the position of the . + + After the is positioned on an attribute, you can call to move to the owner element. + + + +## Examples + The following example uses the and methods to display all the attributes for each book in the `books.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet49"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet49"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet49"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet49"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6021,19 +6017,19 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the next namespace node; otherwise, . If , the position of the is unchanged. - class returns namespace nodes in reverse document order. Therefore, essentially moves to the namespace node above the one in the current scope. - - If the is not currently positioned on a namespace node, this method returns `false` and the position of the does not change. - - When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . - - After the is positioned on an namespace node, call to move back to the element node. - + class returns namespace nodes in reverse document order. Therefore, essentially moves to the namespace node above the one in the current scope. + + If the is not currently positioned on a namespace node, this method returns `false` and the position of the does not change. + + When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . + + After the is positioned on an namespace node, call to move back to the element node. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - + ]]> @@ -6089,19 +6085,19 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the next namespace node; otherwise, . If , the position of the is unchanged. - class returns namespace nodes in reverse document order. - - If the is not currently positioned on a namespace node, this method returns `false` and the position of the does not change. - - When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . - - After the is positioned on an namespace node, call to move back to the element node. - + class returns namespace nodes in reverse document order. + + If the is not currently positioned on a namespace node, this method returns `false` and the position of the does not change. + + When the is positioned on a namespace node, the methods , , and are not applicable. These methods always return `false` and do not change the position of the . + + After the is positioned on an namespace node, call to move back to the element node. + For a definition of namespace nodes, see section 5.4 of the W3C [XML Path Language (XPath)](https://www.w3.org/TR/xpath/all/#data-model) recommendation. - + ]]> @@ -6154,30 +6150,30 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi if the is successful moving to the parent node of the current node; otherwise, . If , the position of the is unchanged. - method depends on the of the current node, and the of the parent node to move to. - - The following table shows the different nodes, and the parent nodes they can move to. - -|XPathNodeType|Parent Node| -|-------------------|-----------------| -|| nodes do not have parents.| -|| or node.| -|| node.| -|| node.| -|| node.| -|| or node.| -|| or node.| -|| or node.| -|| or node.| - - - -## Examples - For an example of the method, see the method. - + method depends on the of the current node, and the of the parent node to move to. + + The following table shows the different nodes, and the parent nodes they can move to. + +|XPathNodeType|Parent Node| +|-------------------|-----------------| +|| nodes do not have parents.| +|| or node.| +|| node.| +|| node.| +|| node.| +|| or node.| +|| or node.| +|| or node.| +|| or node.| + + + +## Examples + For an example of the method, see the method. + ]]> @@ -6278,16 +6274,16 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Moves the to the root node that the current node belongs to. - method, see the method. - + method, see the method. + ]]> @@ -6335,63 +6331,63 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the qualified name of the current node. A that contains the qualified of the current node, or if the current node does not have a name (for example, text or comment nodes). - returned depends on the of the current node. For example, the name for the `` element is `bk:book`. - - The following table lists the value returned by the property, based on the of the current node. - -|XPathNodeType|Property Value| -|-------------------|--------------------| -||The qualified name of the . In the following example, ``, the name of the element node is `bk:book`.| -||The qualified name of the . In the following example, ``, the name of the node is `bk:genre`.| -||The prefix associated with the namespace URI. In the following namespace declaration, `xmlns:bk='urn:samples'`, the property returns `bk`.| -||The target of the . In the following example, ``, the property returns `xml-stylesheet`.| -|All other nodes|.| - - - -## Examples - The following example iterates over the node tree recursively, and displays information about and nodes. - + returned depends on the of the current node. For example, the name for the `` element is `bk:book`. + + The following table lists the value returned by the property, based on the of the current node. + +|XPathNodeType|Property Value| +|-------------------|--------------------| +||The qualified name of the . In the following example, ``, the name of the element node is `bk:book`.| +||The qualified name of the . In the following example, ``, the name of the node is `bk:genre`.| +||The prefix associated with the namespace URI. In the following namespace declaration, `xmlns:bk='urn:samples'`, the property returns `bk`.| +||The target of the . In the following example, ``, the property returns `xml-stylesheet`.| +|All other nodes|.| + + + +## Examples + The following example iterates over the node tree recursively, and displays information about and nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6441,57 +6437,57 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the namespace URI of the current node. A that contains the namespace URI of the current node, or if the current node has no namespace URI. - of the current node. - - The property returns `urn:samples` for the node ``. - - Only and nodes can have a namespace URI. - - - -## Examples - The following example iterates over the node tree recursively, and displays information about and nodes. - + of the current node. + + The property returns `urn:samples` for the node ``. + + Only and nodes can have a namespace URI. + + + +## Examples + The following example iterates over the node tree recursively, and displays information about and nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6541,11 +6537,11 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the of the . An object enabling you to get the atomized version of a within the XML document. - stores atomized strings of any local name, namespace URI, and prefix used by the . This means that when the same is returned multiple times (like "book"), the same object is returned for that . This makes it possible to write efficient code that does object comparisons on these strings, instead of expensive string comparisons. - + stores atomized strings of any local name, namespace URI, and prefix used by the . This means that when the same is returned multiple times (like "book"), the same object is returned for that . This makes it possible to write efficient code that does object comparisons on these strings, instead of expensive string comparisons. + ]]> @@ -6599,53 +6595,53 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Gets an used for equality comparison of objects. An used for equality comparison of objects. - property allows objects to be compared on the basis of position rather than reference to the object. The and methods implemented by this class are based on the position of the objects passed as parameters. The method implemented by this class uses the properties of the node such as its local name and namespace URI to create a hash code for the node. - - - -## Examples - The following example illustrates the use of the property. - + property allows objects to be compared on the basis of position rather than reference to the object. The and methods implemented by this class are based on the position of the objects passed as parameters. The method implemented by this class uses the properties of the node such as its local name and namespace URI to create a hash code for the node. + + + +## Examples + The following example illustrates the use of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet3"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet3"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6693,48 +6689,48 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the of the current node. One of the values representing the current node. - and nodes. - + and nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6787,55 +6783,55 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Gets or sets the markup representing the opening and closing tags of the current node and its child nodes. A that contains the markup representing the opening and closing tags of the current node and its child nodes. - [!NOTE] -> The and properties are not very efficient. If performance is a priority, it is more efficient to use the node navigation methods of the to get values of child nodes. - - - -## Examples - The following example uses the property to display the contents of the first `book` element in the `contosoBooks.xml` file, its child nodes, and its opening and closing tags in the . - +> The and properties are not very efficient. If performance is a priority, it is more efficient to use the node navigation methods of the to get values of child nodes. + + + +## Examples + The following example uses the property to display the contents of the first `book` element in the `contosoBooks.xml` file, its child nodes, and its opening and closing tags in the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet4"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet4"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6883,53 +6879,53 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi When overridden in a derived class, gets the namespace prefix associated with the current node. A that contains the namespace prefix associated with the current node. - property gets the namespace prefix associated with the current node. For example, the property returns `bk` for the `` element. If a prefix does not exist, or the of the current node is not or , the property returns . - - - -## Examples - The following example iterates over the node tree recursively, and displays information about and nodes. - + property gets the namespace prefix associated with the current node. For example, the property returns `bk` for the `` element. If a prefix does not exist, or the of the current node is not or , the property returns . + + + +## Examples + The following example iterates over the node tree recursively, and displays information about and nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet29"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet29"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -6986,61 +6982,61 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi Returns an object used to create a new child node at the beginning of the list of child nodes of the current node. An object used to create a new child node at the beginning of the list of child nodes of the current node. - method. - -- The new child node is not inserted until the method of the object is called. - -- The method is valid only when the is positioned on an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. - + method. + +- The new child node is not inserted until the method of the object is called. + +- The method is valid only when the is positioned on an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet30"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet30"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet30"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The current node the is positioned on does not allow a new child node to be prepended. @@ -7092,61 +7088,61 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi The XML data string for the new child node. Creates a new child node at the beginning of the list of child nodes of the current node using the XML string specified. - ")`. The string for appending the text "book" to the current node's text node is `PrependChild("book")`. If the XML string contains multiple nodes, all nodes are added. - - The following are important notes to consider when using the method. - -- The method is valid only when the is positioned on an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file. - + ")`. The string for appending the text "book" to the current node's text node is `PrependChild("book")`. If the XML string contains multiple nodes, all nodes are added. + + The following are important notes to consider when using the method. + +- The method is valid only when the is positioned on an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet31"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet31"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XML string parameter is . @@ -7200,61 +7196,61 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi An object positioned on the XML data for the new child node. Creates a new child node at the beginning of the list of child nodes of the current node using the XML contents of the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is prepended using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is prepended using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet32"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet32"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet32"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet32"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object is in an error state or closed. @@ -7309,61 +7305,61 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi An object positioned on the node to add as the new child node. Creates a new child node at the beginning of the list of child nodes of the current node using the nodes in the object specified. - method. - -- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. - -- The method is valid only when the is positioned on an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is prepended using the same namespace as the XML document. - + method. + +- If the object is positioned over a sequence of XML nodes, all the nodes in the sequence are added. + +- The method is valid only when the is positioned on an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file using the node contained in the object specified. The `http://www.contoso.com/books` namespace is specified so that the new child element is prepended using the same namespace as the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet33"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet33"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet33"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet33"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object parameter is . @@ -7430,69 +7426,69 @@ navigator.InsertElementBefore(navigator.Prefix, "pages", LookupNamespaceURI(navi The value of the new child element. If or are passed, an empty element is created. Creates a new child element at the beginning of the list of child nodes of the current node using the namespace prefix, local name, and namespace URI specified with the value specified. - or method. For example, the following syntax prepends a child element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: - -```csharp -navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) -``` - - This creates the new child `` element. - - The following are important notes to consider when using the method. - -- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. - -- The method is valid only when the is positioned on an element node. - -- The method does not affect the position of the . - - - -## Examples - In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file. - + or method. For example, the following syntax prepends a child element by using the in-scope namespace `xmlns:bk="http://www.contoso.com/books"`: + +```csharp +navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navigator.Prefix), String.Empty) +``` + + This creates the new child `` element. + + The following are important notes to consider when using the method. + +- If the namespace prefix specified is `null` or , then the prefix for the namespace URI of the new element is obtained from the current namespaces in-scope. If there is no namespace prefix assigned to the specified namespace URI at the current scope, then a namespace prefix is automatically generated. + +- The method is valid only when the is positioned on an element node. + +- The method does not affect the position of the . + + + +## Examples + In the following example, a new `pages` child element is prepended to the beginning of the list of child elements of the first `book` element in the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet34"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet34"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet34"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet34"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The current node the is positioned on does not allow a new child node to be prepended. @@ -7542,65 +7538,65 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi Returns an object that contains the current node and its child nodes. An object that contains the current node and its child nodes. - object is created with the current node and its child nodes, the object's property is set to . When the object's method is called for the first time, the is moved to the current node of the . The new object continues to read until the end of the XML tree is reached. At this point, the method returns `false` and the object's property is set to . - + object is created with the current node and its child nodes, the object's property is set to . When the object's method is called for the first time, the is moved to the current node of the . The new object continues to read until the end of the XML tree is reached. At this point, the method returns `false` and the object's property is set to . + > [!NOTE] -> Changing the position of the object does not affect the position of the . - - Namespace declarations for the in-scope namespaces of the current node are not inserted into the XML stream provided to the object. - +> Changing the position of the object does not affect the position of the . + + Namespace declarations for the in-scope namespaces of the current node are not inserted into the XML stream provided to the object. + > [!NOTE] -> This behavior differs from the method. - - This method creates the object with specific reader settings, and the module that uses this method has no control over those settings. For example, the reader returned by this method prohibits processing Data Type Definitions (DTDs). If the reader attempts to read a file that uses a DTD, it will throw an error, . The message for the exception will be `Unexpected DTD declaration`. - - You can change this behavior by implementing a custom that returns an with the desired . - - - -## Examples - The following example illustrates using the method on the first `book` element of the `contosoBooks.xml` file. - +> This behavior differs from the method. + + This method creates the object with specific reader settings, and the module that uses this method has no control over those settings. For example, the reader returned by this method prohibits processing Data Type Definitions (DTDs). If the reader attempts to read a file that uses a DTD, it will throw an error, . The message for the exception will be `Unexpected DTD declaration`. + + You can change this behavior by implementing a custom that returns an with the desired . + + + +## Examples + The following example illustrates using the method on the first `book` element of the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet35"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet35"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet35"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet35"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The is not positioned on an element node or the root node. @@ -7652,56 +7648,56 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi Replaces a range of sibling nodes from the current node to the node specified. An object used to specify the replacement range. - method replaces a range of sibling nodes from the current node the is positioned on (inclusive) to the node specified by the parameter (inclusive). - + method replaces a range of sibling nodes from the current node the is positioned on (inclusive) to the node specified by the parameter (inclusive). + > [!NOTE] -> The replacement range is not inserted until the method of the object is called. - - - -## Examples - In the following example, the first and second `book` elements of the `contosoBooks.xml` file are replaced with a new empty `book` element using the method. - +> The replacement range is not inserted until the method of the object is called. + + + +## Examples + In the following example, the first and second `book` elements of the `contosoBooks.xml` file are replaced with a new empty `book` element using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet53"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet53"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet53"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet53"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The specified is . @@ -7763,61 +7759,61 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi The XML data string for the new node. Replaces the current node with the content of the string specified. - is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. - -- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. - -- The method is not equivalent to the method. - - - -## Examples - In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. - + is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. + +- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. + +- The method is not equivalent to the method. + + + +## Examples + In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet36"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet36"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet36"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet36"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XML string parameter is . @@ -7871,61 +7867,61 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi An object positioned on the XML data for the new node. Replaces the current node with the contents of the object specified. - is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. - -- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. - -- The method is not equivalent to the method. - - - -## Examples - In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. - + is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. + +- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. + +- The method is not equivalent to the method. + + + +## Examples + In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet37"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet37"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet37"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet37"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object is in an error state or closed. @@ -7980,61 +7976,61 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi An object positioned on the new node. Replaces the current node with the contents of the object specified. - is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. - -- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. - -- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. - -- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. - -- The method is not equivalent to the method. - - - -## Examples - In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. - + is positioned on the new node on completion of the method and returns `true`. The is not positioned on the new node after completion of the method when the XML input is in which case the is either positioned on the next sibling node or the parent node if there is no next sibling node to the replaced node and the returns `false`. + +- The method is valid only when the is positioned on an element, text, processing instruction, or comment node. + +- If the XML data string is not well-formed than an exception is thrown and the result of this method is equivalent to calling on the current node. + +- If the XML string contains multiple nodes, all nodes are added and the is positioned on the first node in the series of nodes. + +- The method is not equivalent to the method. + + + +## Examples + In the following example the `price` element in the `contosoBooks.xml` file is replaced by a new `pages` element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet38"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet38"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet38"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet38"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The object parameter is . @@ -8091,11 +8087,11 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi Gets the schema information that has been assigned to the current node as a result of schema validation. An object that contains the schema information for the current node. - , , or on nodes with a non-`null` . If the current node is not one of the above node types, or if the instance does not report schema information, the property returns `null`. - + , , or on nodes with a non-`null` . If the current node is not one of the above node types, or if the instance does not report schema information, the property returns `null`. + ]]> @@ -8156,73 +8152,73 @@ navigator.PrependChildElement(navigator.Prefix, "pages", LookupNamespaceURI(navi Selects a node set, using the specified XPath expression. An pointing to the selected node set. - when this method is called. After calling this method, the returned represents the set of selected nodes. Use method of the to iterate over the selected node set. - - The following C# code iterates over the selected set of nodes. - -```csharp -XPathNodeIterator iterator = nav.Select("/bookstore/book"); -while (iterator.MoveNext()) -{ - Console.WriteLine(Iterator.Current.Name); -} -``` - - The following are important notes to consider when using the method. - -- You can still use any of the object's navigation methods to move within the . The navigation methods are independent of the selected nodes in the . - -- Future calls to the method return a new object that points to the selected set of nodes that matches the new call. The two objects are completely independent of each other. - -- If the XPath expression requires namespace resolution, use the overload, which takes an as its argument. - -- This method has no effect on the state of the . - - - -## Examples - The following example uses the method to select a node set. - + when this method is called. After calling this method, the returned represents the set of selected nodes. Use method of the to iterate over the selected node set. + + The following C# code iterates over the selected set of nodes. + +```csharp +XPathNodeIterator iterator = nav.Select("/bookstore/book"); +while (iterator.MoveNext()) +{ + Console.WriteLine(Iterator.Current.Name); +} +``` + + The following are important notes to consider when using the method. + +- You can still use any of the object's navigation methods to move within the . The navigation methods are independent of the selected nodes in the . + +- Future calls to the method return a new object that points to the selected set of nodes that matches the new call. The two objects are completely independent of each other. + +- If the XPath expression requires namespace resolution, use the overload, which takes an as its argument. + +- This method has no effect on the state of the . + + + +## Examples + The following example uses the method to select a node set. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet39"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet39"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet39"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet39"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XPath expression contains an error or its return type is not a node set. @@ -8281,117 +8277,117 @@ while (iterator.MoveNext()) Selects a node set using the specified . An that points to the selected node set. - when you called this method. After you call this method, the returned represents the set of selected nodes. Use on the to iterate over the selected node set. - - The following C# code iterates over the selected set of nodes. - -```csharp -XPathNodeIterator ni = nav.Select(expr); -while (ni.MoveNext()) -{ - Console.WriteLine(ni.Current.Name); -} -``` - - The following are important notes to consider when using the method. - -- You can still use any of the object's navigation methods to move within the . The navigation methods are independent of the selected nodes in the . - -- Future calls to the method return a new object that points to the selected set of nodes that matches the new call. The two objects are completely independent of each other. - -- If the requires namespace resolution, the prefix and namespace URI pair must be added to an , and the method must be called to specify the to use for namespace resolution. - - For example, suppose the document contains the following XML nodes. - -```xml - - - Pride And Prejudice - - -``` - - In this case, the following C# code selects the `bk:ISBN` node. - -```csharp -XPathExpression expr = nav.Compile("book/@bk:ISBN"); -XmlNamespaceManager mngr = new XmlNamespaceManager(new NameTable()); -mngr.AddNamespace("bk","urn:samples"); -expr.SetContext(mngr); -XPathNodeIterator ni = nav.Select(expr); -``` - + when you called this method. After you call this method, the returned represents the set of selected nodes. Use on the to iterate over the selected node set. + + The following C# code iterates over the selected set of nodes. + +```csharp +XPathNodeIterator ni = nav.Select(expr); +while (ni.MoveNext()) +{ + Console.WriteLine(ni.Current.Name); +} +``` + + The following are important notes to consider when using the method. + +- You can still use any of the object's navigation methods to move within the . The navigation methods are independent of the selected nodes in the . + +- Future calls to the method return a new object that points to the selected set of nodes that matches the new call. The two objects are completely independent of each other. + +- If the requires namespace resolution, the prefix and namespace URI pair must be added to an , and the method must be called to specify the to use for namespace resolution. + + For example, suppose the document contains the following XML nodes. + +```xml + + + Pride And Prejudice + + +``` + + In this case, the following C# code selects the `bk:ISBN` node. + +```csharp +XPathExpression expr = nav.Compile("book/@bk:ISBN"); +XmlNamespaceManager mngr = new XmlNamespaceManager(new NameTable()); +mngr.AddNamespace("bk","urn:samples"); +expr.SetContext(mngr); +XPathNodeIterator ni = nav.Select(expr); +``` + > [!NOTE] -> If the does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the method and provide an that contains a prefix and namespace URI to handle the default namespace. - - For example, suppose you have the following XML. - -```xml - - - Pride And Prejudice - - -``` - - In this case, the following C# code selects all book nodes: - -```csharp -XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable); -nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); -XPathExpression expr; -expr = nav.Compile("//ab:book"); -expr.SetContext(nsmgr); -XPathNodeIterator ni = nav.Select(expr); -``` - - This method has no effect on the state of the . - - - -## Examples - The following example uses the method to select a node set. - +> If the does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the method and provide an that contains a prefix and namespace URI to handle the default namespace. + + For example, suppose you have the following XML. + +```xml + + + Pride And Prejudice + + +``` + + In this case, the following C# code selects all book nodes: + +```csharp +XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable); +nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); +XPathExpression expr; +expr = nav.Compile("//ab:book"); +expr.SetContext(nsmgr); +XPathNodeIterator ni = nav.Select(expr); +``` + + This method has no effect on the state of the . + + + +## Examples + The following example uses the method to select a node set. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet40"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet40"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet40"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet40"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XPath expression contains an error or its return type is not a node set. @@ -8459,48 +8455,48 @@ XPathNodeIterator ni = nav.Select(expr); Selects a node set using the specified XPath expression with the object specified to resolve namespace prefixes. An that points to the selected node set. - method with the object specified to resolve namespace prefixes in the XPath expression. - + method with the object specified to resolve namespace prefixes in the XPath expression. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet41"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet41"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet41"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet41"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The XPath expression contains an error or its return type is not a node set. @@ -8565,16 +8561,16 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the ancestor nodes of the current node that have a matching . An that contains the selected nodes. The returned nodes are in reverse document order. - method has no effect on the state of the . - - - -## Examples - For an example of selecting ancestor nodes, see . - + method has no effect on the state of the . + + + +## Examples + For an example of selecting ancestor nodes, see . + ]]> @@ -8633,55 +8629,55 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the ancestor nodes of the current node that have the specified local name and namespace URI. An that contains the selected nodes. The returned nodes are in reverse document order. - is specified as the `name` parameter, all ancestor nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all ancestor nodes with the specified local name that belong to no namespace are selected. If is specified as both the local name and namespace URI, all ancestor nodes that belong to no namespace are selected. - - The method has no effect on the state of the . - - - -## Examples - The following example illustrates selecting ancestor, child, and descendant nodes. - + is specified as the `name` parameter, all ancestor nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all ancestor nodes with the specified local name that belong to no namespace are selected. If is specified as both the local name and namespace URI, all ancestor nodes that belong to no namespace are selected. + + The method has no effect on the state of the . + + + +## Examples + The following example illustrates selecting ancestor, child, and descendant nodes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet42"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet42"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet42"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet42"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -8747,16 +8743,16 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the child nodes of the current node that have the matching . An that contains the selected nodes. - method has no effect on the state of the . - - - -## Examples - For an example of selecting ancestor, child and descendant nodes, see . - + method has no effect on the state of the . + + + +## Examples + For an example of selecting ancestor, child and descendant nodes, see . + ]]> @@ -8813,18 +8809,18 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the child nodes of the current node that have the local name and namespace URI specified. An that contains the selected nodes. - is specified as the `name` parameter, all child nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all child nodes with the specified local name that belong to no namespace are selected. If both the local name and namespace URI parameters are , all child nodes that belong to no namespace are selected. - - The method has no effect on the state of the . - - - -## Examples - For an example of selecting ancestor, child and descendant nodes, see . - + is specified as the `name` parameter, all child nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all child nodes with the specified local name that belong to no namespace are selected. If both the local name and namespace URI parameters are , all child nodes that belong to no namespace are selected. + + The method has no effect on the state of the . + + + +## Examples + For an example of selecting ancestor, child and descendant nodes, see . + ]]> @@ -8893,16 +8889,16 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the descendant nodes of the current node that have a matching . An that contains the selected nodes. - method has no effect on the state of the . - - - -## Examples - For an example of selecting ancestor, child and descendant nodes, see . - + method has no effect on the state of the . + + + +## Examples + For an example of selecting ancestor, child and descendant nodes, see . + ]]> @@ -8962,20 +8958,20 @@ XPathNodeIterator ni = nav.Select(expr); Selects all the descendant nodes of the current node with the local name and namespace URI specified. An that contains the selected nodes. - is specified as the `name` parameter, all descendant nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all descendant nodes with the specified local name that belong to no namespace are selected. If both the local name and namespace URI parameters are , all descendant nodes that belong to no namespace are selected. - - A descendant is a child or a child of a child and so on; thus the selected nodes will never contain attribute or namespace nodes. - - The method has no effect on the state of the . - - - -## Examples - For an example of selecting ancestor, child, and descendant nodes, see . - + is specified as the `name` parameter, all descendant nodes that belong to the specified namespace URI are selected. If is specified as the `namespaceURI` parameter, all descendant nodes with the specified local name that belong to no namespace are selected. If both the local name and namespace URI parameters are , all descendant nodes that belong to no namespace are selected. + + A descendant is a child or a child of a child and so on; thus the selected nodes will never contain attribute or namespace nodes. + + The method has no effect on the state of the . + + + +## Examples + For an example of selecting ancestor, child, and descendant nodes, see . + ]]> @@ -9047,53 +9043,53 @@ XPathNodeIterator ni = nav.Select(expr); Selects a single node in the using the specified XPath query. An object that contains the first matching node for the XPath query specified; otherwise, if there are no query results. - method selects the first node that matches the XPath query in the object. - - - -## Examples - The following example selects a single node from the based on the XPath query specified. - + method selects the first node that matches the XPath query in the object. + + + +## Examples + The following example selects a single node from the based on the XPath query specified. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet43"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet43"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet43"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet43"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> An error was encountered in the XPath query or the return type of the XPath expression is not a node. @@ -9153,53 +9149,53 @@ XPathNodeIterator ni = nav.Select(expr); Selects a single node in the using the specified object. An object that contains the first matching node for the XPath query specified; otherwise if there are no query results. - method selects the first node that matches the compiled XPath query contained in the object in the . - - - -## Examples - The following example selects a single node from the based on the XPath query contained in the . - + method selects the first node that matches the compiled XPath query contained in the object in the . + + + +## Examples + The following example selects a single node from the based on the XPath query contained in the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet44"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet44"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet44"::: - - The example takes the `books.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet44"::: + + The example takes the `books.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> An error was encountered in the XPath query or the return type of the XPath expression is not a node. @@ -9262,56 +9258,56 @@ XPathNodeIterator ni = nav.Select(expr); Selects a single node in the object using the specified XPath query with the object specified to resolve namespace prefixes. An object that contains the first matching node for the XPath query specified; otherwise if there are no query results. - method selects the first node that matches the XPath query specified. The method uses the object to resolve namespace prefixes. - + method selects the first node that matches the XPath query specified. The method uses the object to resolve namespace prefixes. + > [!NOTE] -> In XPath all namespaces must be prefixed in a query. If an XML document uses a default namespace, you must still add a namespace prefix to the object. - - - -## Examples - The following example selects a single node from the object based on the XPath query specified and uses the object specified to resolve namespace prefixes in the XPath query. - +> In XPath all namespaces must be prefixed in a query. If an XML document uses a default namespace, you must still add a namespace prefix to the object. + + + +## Examples + The following example selects a single node from the object based on the XPath query specified and uses the object specified to resolve namespace prefixes in the XPath query. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet45"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet45"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet45"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet45"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> An error was encountered in the XPath query or the return type of the XPath expression is not a node. @@ -9363,55 +9359,55 @@ XPathNodeIterator ni = nav.Select(expr); The new typed value of the node. Sets the typed value of the current node. - object is created as the result of a schema validating object, the value specified to the method is verified against the XML Schema Definition Language (XSD) schema for the XML document. If the value specified is invalid according to the schema for the XML document, an is thrown. - - The method is valid only when the is positioned on an element or attribute node. - - - -## Examples - In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file using the object to resolve namespace prefixes in the XPath expression. - + object is created as the result of a schema validating object, the value specified to the method is verified against the XML Schema Definition Language (XSD) schema for the XML document. If the value specified is invalid according to the schema for the XML document, an is thrown. + + The method is valid only when the is positioned on an element or attribute node. + + + +## Examples + In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file using the object to resolve namespace prefixes in the XPath expression. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet46"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet46"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet46"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet46"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The does not support the type of the object specified. @@ -9465,56 +9461,56 @@ XPathNodeIterator ni = nav.Select(expr); The new value of the node. Sets the value of the current node. - is positioned on an element node with complex content (child elements), calling the method replaces the child elements with a text node containing the new string value. - -- The method cannot update the root node or namespace nodes. - - - -## Examples - In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file using the object to resolve namespace prefixes in the XPath expression. - + is positioned on an element node with complex content (child elements), calling the method replaces the child elements with a text node containing the new string value. + +- The method cannot update the root node or namespace nodes. + + + +## Examples + In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file using the object to resolve namespace prefixes in the XPath expression. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet47"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet47"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet47"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet47"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> The value parameter is . @@ -9574,13 +9570,13 @@ XPathNodeIterator ni = nav.Select(expr); Creates a new copy of the object. A new copy of the object. - 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 . + ]]> @@ -9629,22 +9625,22 @@ XPathNodeIterator ni = nav.Select(expr); Gets the text value of the current node. A that contains the text value of the current node. - method depends on the of the node. - -|XPathNodeType|Property Value| -|-------------------|--------------------| -||The of the root node.| -||The of the element.| -||The value of the attribute.| -||The content of the text node.| -||The entire content excluding the target.| -||The content of the comment.| -||The white space between mark-up.| -||The white space between markup in a mixed content model, or white space within an `xml:space='preserve'` scope.| - + method depends on the of the node. + +|XPathNodeType|Property Value| +|-------------------|--------------------| +||The of the root node.| +||The of the element.| +||The value of the attribute.| +||The content of the text node.| +||The entire content excluding the target.| +||The content of the comment.| +||The white space between mark-up.| +||The white space between markup in a mixed content model, or white space within an `xml:space='preserve'` scope.| + ]]> @@ -9691,26 +9687,26 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node as a boxed object of the most appropriate .NET type. The current node as a boxed object of the most appropriate .NET type. - property returns a boxed of the most appropriate .NET . If the element or attribute's content is a list type, the property returns an array of objects of the most appropriate .NET . - - The following table describes the returned by each . - -|XPathNodeType|TypedValue Returned| -|-------------------|-------------------------| -||Returns a object containing all node descendants of the document, concatenated and separated by white space. If the document does not have any node children, is returned.| -|

(typed or simple content)|Returns an that represents the typed value of the .

If the is defined as an XML Schema list data type, then the node value is exposed as an array of objects. Each in the array contains the typed value of a child of the element.| -|

(untyped, mixed, or complex content)|Returns a object containing all node descendants of the (including string representations of typed values), concatenated and separated by white space. If the does not have any node children, is returned.| -|

(typed or simple content)|Returns an that represents the typed value of the . The is boxed as a .NET value.

If the is defined as an XML Schema list data type, the node value is exposed as an array of objects. Each in the array contains the typed value of a child of the .| -||A object containing the text.| -||A object containing the content of the comments, excluding the surrounding ``.| -||A object containing the content of the processing instruction, excluding the target and surrounding ``.| -||A object containing the namespace name.| -||A object containing the text of the node.| -||A object containing the text of the node.| - + property returns a boxed of the most appropriate .NET . If the element or attribute's content is a list type, the property returns an array of objects of the most appropriate .NET . + + The following table describes the returned by each . + +|XPathNodeType|TypedValue Returned| +|-------------------|-------------------------| +||Returns a object containing all node descendants of the document, concatenated and separated by white space. If the document does not have any node children, is returned.| +|

(typed or simple content)|Returns an that represents the typed value of the .

If the is defined as an XML Schema list data type, then the node value is exposed as an array of objects. Each in the array contains the typed value of a child of the element.| +|

(untyped, mixed, or complex content)|Returns a object containing all node descendants of the (including string representations of typed values), concatenated and separated by white space. If the does not have any node children, is returned.| +|

(typed or simple content)|Returns an that represents the typed value of the . The is boxed as a .NET value.

If the is defined as an XML Schema list data type, the node value is exposed as an array of objects. Each in the array contains the typed value of a child of the .| +||A object containing the text.| +||A object containing the content of the comments, excluding the surrounding ``.| +||A object containing the content of the processing instruction, excluding the target and surrounding ``.| +||A object containing the namespace name.| +||A object containing the text of the node.| +||A object containing the text of the node.| + ]]> @@ -9764,18 +9760,18 @@ XPathNodeIterator ni = nav.Select(expr); Used by implementations which provide a "virtualized" XML view over a store, to provide access to underlying objects. The default is . - property can be used by implementations which provide a "virtualized" XML view over a store, to provide access to underlying objects. For example, if an object is used to provide a virtual XML view over a Common Language Runtime (CLR) object graph, you may wish to perform XPath queries using the method and then access the CLR objects underlying the selected nodes. The property would expose these underlying objects. - - In many cases, this value will be `null`, and the object returned by the property will always be implementation specific. - - The property should preserve object identity and should only be used to return objects that have a one-to-one correspondence to their respective overlaid items. A user should always get the same object on successive visits to the same node using the same object or a cloned one. - + property can be used by implementations which provide a "virtualized" XML view over a store, to provide access to underlying objects. For example, if an object is used to provide a virtual XML view over a Common Language Runtime (CLR) object graph, you may wish to perform XPath queries using the method and then access the CLR objects underlying the selected nodes. The property would expose these underlying objects. + + In many cases, this value will be `null`, and the object returned by the property will always be implementation specific. + + The property should preserve object identity and should only be used to return objects that have a one-to-one correspondence to their respective overlaid items. A user should always get the same object on successive visits to the same node using the same object or a cloned one. + > [!NOTE] -> The property of an object created by an object returns the corresponding . - +> The property of an object created by an object returns the corresponding . + ]]> @@ -9866,13 +9862,13 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as the specified, using the object specified to resolve namespace prefixes. The value of the current node as the requested. - method attempts to convert the value of the current node to the .NET type, specified according to the XPath 2.0 rules for casting the current node's type. - - The object is used to resolve namespace prefixes related to type conversions. For example, when converting an `xs:QName` to an `xs:string`. - + method attempts to convert the value of the current node to the .NET type, specified according to the XPath 2.0 rules for casting the current node's type. + + The object is used to resolve namespace prefixes related to type conversions. For example, when converting an `xs:QName` to an `xs:string`. + ]]> The current node's value is not in the correct format for the target type. @@ -9921,33 +9917,33 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as a . The current node's value as a . - has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:boolean` type, the property returns the current node's value as an unboxed object. - - However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:boolean`. - - - -## Examples - In the following example, the value of each element in the `valueas.xml` file is returned using the , , , , and properties. - + has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:boolean` type, the property returns the current node's value as an unboxed object. + + However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:boolean`. + + + +## Examples + In the following example, the value of each element in the `valueas.xml` file is returned using the , , , , and properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet5"::: - - The example takes the `valueas.xml` file as an input. - -```xml - - true - 2004-04-20T12:00:00 - 10.00 - 100000000 - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet5"::: + + The example takes the `valueas.xml` file as an input. + +```xml + + true + 2004-04-20T12:00:00 + 10.00 + 100000000 + +``` + ]]> The current node's string value cannot be converted to a . @@ -9996,18 +9992,18 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as a . The current node's value as a . - has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:datetime` type, the property returns the current node's value as an unboxed object. - - However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:datetime`. - - - -## Examples - For an example of the property, see the property. - + has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:datetime` type, the property returns the current node's value as an unboxed object. + + However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:datetime`. + + + +## Examples + For an example of the property, see the property. + ]]> The current node's string value cannot be converted to a . @@ -10056,18 +10052,18 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as a . The current node's value as a . - has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:double` type, the property returns the current node's value as an unboxed object. - - However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xsd:double`. - - - -## Examples - For an example of the property, see the property. - + has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:double` type, the property returns the current node's value as an unboxed object. + + However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xsd:double`. + + + +## Examples + For an example of the property, see the property. + ]]> The current node's string value cannot be converted to a . @@ -10116,18 +10112,18 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as an . The current node's value as an . - has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:integer` type, the property returns the current node's value as an unboxed object. - - However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:integer`. - - - -## Examples - For an example of the property, see the property. - + has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:integer` type, the property returns the current node's value as an unboxed object. + + However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:integer`. + + + +## Examples + For an example of the property, see the property. + ]]> The current node's string value cannot be converted to a . @@ -10176,18 +10172,18 @@ XPathNodeIterator ni = nav.Select(expr); Gets the current node's value as an . The current node's value as an . - has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:integer` type, the property returns the current node's value as an unboxed object. - - However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:integer`. - - - -## Examples - For an example of the property, see the property. - + has schema or type information (for example, from an object initialized with an XML schema validating ), and if the current node is defined as an XML Schema `xs:integer` type, the property returns the current node's value as an unboxed object. + + However, if the does not have any schema or type information, the property attempts to convert the string value of the current node to a value, according to the XPath 2.0 casting rules for `xs:integer`. + + + +## Examples + For an example of the property, see the property. + ]]> The current node's string value cannot be converted to a . @@ -10236,91 +10232,91 @@ XPathNodeIterator ni = nav.Select(expr); Gets the .NET of the current node. The .NET of the current node. The default value is . - property gets the .NET of the typed value of the current node. - - For example, an element of type `xs:int` would have a of by default. However, the could be any one of the valid types that can be mapped to `xs:int` such as or . - + property gets the .NET of the typed value of the current node. + + For example, an element of type `xs:int` would have a of by default. However, the could be any one of the valid types that can be mapped to `xs:int` such as or . + If a node has no type, this is equivalent to the type annotation on the node being `xdt:untypedAtomic`. In this case, the property returns a string for the node. For more information, see [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes). - -## Examples - In the following example, the `contosoBooks.xml` XML file and `contosoBooks.xsd` XML Schema definition language (XSD) schema are used to create an object. The typed value of the `price` element is displayed using the property and then returned as a string using the method. - + +## Examples + In the following example, the `contosoBooks.xml` XML file and `contosoBooks.xsd` XML Schema definition language (XSD) schema are used to create an object. The typed value of the `price` element is displayed using the property and then returned as a string using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorProperties/CPP/xpathnavigatorproperties.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/CanEdit/xpathnavigatorproperties.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet6"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - - The example also takes the `contosoBooks.xsd` as an input. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorProperties/VB/xpathnavigatorproperties.vb" id="Snippet6"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + + The example also takes the `contosoBooks.xsd` as an input. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + ]]> @@ -10370,70 +10366,70 @@ XPathNodeIterator ni = nav.Select(expr); The object to stream to. Streams the current node and its child nodes to the object specified. - object specified. - - For example, if the method is called on the first `book` element of the `books.xml` file, the `http://www.contoso.com/books` namespace declaration made at the top of the XML document will appear in the XML streamed to the object specified as shown in the following example. - -```xml - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - -``` - + object specified. + + For example, if the method is called on the first `book` element of the `books.xml` file, the `http://www.contoso.com/books` namespace declaration made at the top of the XML document will appear in the XML streamed to the object specified as shown in the following example. + +```xml + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + +``` + > [!NOTE] -> The method does not affect the position of the . - - - -## Examples - The following example illustrates using the method on the first `book` element of the `contosoBooks.xml` file. - +> The method does not affect the position of the . + + + +## Examples + The following example illustrates using the method on the first `book` element of the `contosoBooks.xml` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XPathNavigatorMethods/CPP/xpathnavigatormethods.cpp" id="Snippet48"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.XPath/XPathNavigator/AppendChild/xpathnavigatormethods.cs" id="Snippet48"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet48"::: - - The example takes the `contosoBooks.xml` file as an input. - -```xml - - - - - The Autobiography of Benjamin Franklin - - Benjamin - Franklin - - 8.99 - - - The Confidence Man - - Herman - Melville - - 11.99 - - - The Gorgias - - Plato - - 9.99 - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb" id="Snippet48"::: + + The example takes the `contosoBooks.xml` file as an input. + +```xml + + + + + The Autobiography of Benjamin Franklin + + Benjamin + Franklin + + 8.99 + + + The Confidence Man + + Herman + Melville + + 11.99 + + + The Gorgias + + Plato + + 9.99 + + + +``` + ]]> @@ -10484,17 +10480,17 @@ XPathNodeIterator ni = nav.Select(expr); Gets the xml:lang scope for the current node. A that contains the value of the xml:lang scope, or if the current node has no xml:lang scope value to return. - is positioned on the `name` element, the property returns a scope of `en-us` indicating that the node is in the scope of a `xml:lang="en-us"` attribute. - -```xml - - Name - -``` - + is positioned on the `name` element, the property returns a scope of `en-us` indicating that the node is in the scope of a `xml:lang="en-us"` attribute. + +```xml + + Name + +``` + ]]> @@ -10547,17 +10543,17 @@ XPathNodeIterator ni = nav.Select(expr); Gets the information for the current node. An object; default is . - property. - -- The property is `null`, unless the property of the property of the is set to . - -- If this node is valid, the property is the same as the property of the property of the , unless this node is a member of a union. - -- If this node is a member of a union, the property is the same as the property of the property of this . - + property. + +- The property is `null`, unless the property of the property of the is set to . + +- If this node is valid, the property is the same as the property of the property of the , unless this node is a member of a union. + +- If this node is a member of a union, the property is the same as the property of the property of this . + ]]> diff --git a/xml/System.Xml.Xsl/XslCompiledTransform.xml b/xml/System.Xml.Xsl/XslCompiledTransform.xml index 9cfd2c9cf63..aa88980fb6e 100644 --- a/xml/System.Xml.Xsl/XslCompiledTransform.xml +++ b/xml/System.Xml.Xsl/XslCompiledTransform.xml @@ -1180,9 +1180,7 @@ xslt.Load(typeof(bookOrders)); An with default settings is used to load the input document. DTD processing is disabled on the . If you require DTD processing, create an with this feature enabled, and pass it to the method. - This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload which takes an as the input argument. - - + This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload that takes an as the input argument. ## Examples The following example executes an XSLT transformation and outputs to an object. @@ -1321,7 +1319,7 @@ xslt.Load(typeof(bookOrders)); ## Remarks If the XSLT `document()` function is enabled, it is resolved using an with no user credentials. If the external resource is located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload which takes an as the input argument. + This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload that takes an as the input argument. The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. @@ -1857,7 +1855,7 @@ xslt.Load(typeof(bookOrders)); ## Remarks If the XSLT `document()` function is enabled, it is resolved using an with no user credentials. If the external resource is located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload which takes an as the input argument. + This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload that takes an as the input argument. The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. @@ -1940,7 +1938,7 @@ xslt.Load(typeof(bookOrders)); ## Remarks If the XSLT `document()` function is enabled, it is resolved using an with no user credentials. If the external resource is located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload which takes an as the input argument. + This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload that takes an as the input argument. The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. @@ -2017,7 +2015,7 @@ xslt.Load(typeof(bookOrders)); ## Remarks If the XSLT `document()` function is enabled, it is resolved using an with no user credentials. If the external resource is located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload which takes an as the input argument. + This method does not support the `xsl:strip-space` element. If your compiled style sheet included the `xsl:strip-space` element, you must use the overload that takes an as the input argument. The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. diff --git a/xml/System.Xml.Xsl/XslTransform.xml b/xml/System.Xml.Xsl/XslTransform.xml index 8c79c694adc..7f4f3816743 100644 --- a/xml/System.Xml.Xsl/XslTransform.xml +++ b/xml/System.Xml.Xsl/XslTransform.xml @@ -271,7 +271,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl="http://www.w3.org/1999/XSL/Transform"`. - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. If the style sheet contains embedded scripting, the script is compiled to an assembly. The URI of the style sheet is used to create evidence, which is applied to the assembly. @@ -360,7 +360,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). @@ -453,7 +453,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. @@ -523,7 +523,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource that requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. The style sheet is loaded from the current position of the . To use just a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). @@ -615,10 +615,8 @@ > [!NOTE] > If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - - ## Examples - The following example transforms an XML document into an HTML document. The example loads an XSLT style sheet which contains an `xsl:include` element referencing another style sheet. An is passed to the method which sets the credentials necessary to access the network resource for the included style sheet. + The following example transforms an XML document into an HTML document. The example loads an XSLT style sheet that contains an `xsl:include` element referencing another style sheet. An is passed to the method, which sets the credentials necessary to access the network resource for the included style sheet. :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load2/VB/trans2.vb" id="Snippet1"::: @@ -969,7 +967,7 @@ |The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the class.| ## Examples - The following example performs an XSLT transformation where `xsltReader` is an containing a style sheet and `secureURL` is a trusted URL that can be used to create . The method is used to create which is applied to the style sheet. + The following example performs an XSLT transformation where `xsltReader` is an containing a style sheet and `secureURL` is a trusted URL that can be used to create . The method is used to create , which is applied to the style sheet. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Load4/CPP/trans_ev.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans_ev.cs" id="Snippet1"::: @@ -1225,9 +1223,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. > [!NOTE] -> This method is obsolete in version 1.1 of the .NET Framework. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - +> This method is obsolete in version 1.1 of the .NET Framework. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. ## Examples The following example transforms the `books.xml` file using the `output.xsl` style sheet and outputs the results to the `books.html` file. @@ -1321,7 +1317,7 @@ supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (the `xsl:output` element is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. @@ -1458,7 +1454,7 @@ Root node is book. This method enables you to do an asynchronous transformation of the source document. > [!NOTE] -> This method is obsolete. The setting of the property determines how the XSLT document() function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is obsolete. The setting of the property determines how the XSLT document() function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. ]]> @@ -1619,7 +1615,7 @@ Root node is book. supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. The `args` are matched with the `xsl:param` elements defined in the style sheet. @@ -1752,7 +1748,7 @@ Root node is book. supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. The `args` are matched with the `xsl:param` elements defined in the style sheet. @@ -2030,7 +2026,7 @@ Root node is book. supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. @@ -2167,7 +2163,7 @@ Root node is book. See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. ]]> @@ -2252,7 +2248,7 @@ Root node is book. The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. ]]> @@ -2425,7 +2421,7 @@ Root node is book. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method that takes an object as one of its arguments. ]]> diff --git a/xml/System.Xml.Xsl/XsltException.xml b/xml/System.Xml.Xsl/XsltException.xml index 889da4ea383..e15a8b6031f 100644 --- a/xml/System.Xml.Xsl/XsltException.xml +++ b/xml/System.Xml.Xsl/XsltException.xml @@ -248,7 +248,7 @@ The description of the error condition. - The which threw the , if any. This value can be . + The that threw the , if any. This value can be . Initializes a new instance of the class. To be added. @@ -357,11 +357,11 @@ Gets the line number indicating where the error occurred in the style sheet. The line number indicating where the error occurred in the style sheet. - class. - + class. + ]]> @@ -414,11 +414,11 @@ Gets the line position indicating where the error occurred in the style sheet. The line position indicating where the error occurred in the style sheet. - class. - + class. + ]]> diff --git a/xml/System.Xml/XmlConvert.xml b/xml/System.Xml/XmlConvert.xml index 6f2487e63be..041bb47ba17 100644 --- a/xml/System.Xml/XmlConvert.xml +++ b/xml/System.Xml/XmlConvert.xml @@ -388,7 +388,7 @@ - Calling this method on a node type which cannot be imported. + The node type can't be imported. @@ -5062,7 +5062,7 @@ doc.Save(Console.Out); - If the document was loaded with a class that extends `XmlReader` and the `XmlReader` cannot resolve entities ( returns `false`), the `XmlResolver` on the `XmlDocument` is used to resolve any references in the DocumentType node and to expand any entity references. > [!NOTE] -> If the `XmlDocument` is loaded using an which had an `XmlResolver` set to it, the `XmlResolver` on the `XmlReader` is not cached by the `XmlDocument` after completes. +> If the `XmlDocument` is loaded using an that had an `XmlResolver` set to it, the `XmlResolver` on the `XmlReader` is not cached by the `XmlDocument` after completes. In version 1.1 of the.NET Framework, if this property is not set, the trust level of the application determines the default behavior. diff --git a/xml/System.Xml/XmlNamespaceManager.xml b/xml/System.Xml/XmlNamespaceManager.xml index 70e51ac7961..c3e1e15e168 100644 --- a/xml/System.Xml/XmlNamespaceManager.xml +++ b/xml/System.Xml/XmlNamespaceManager.xml @@ -67,88 +67,88 @@ Resolves, adds, and removes namespaces to a collection and provides scope management for these namespaces. - stores prefixes and namespaces as strings. Here's a summary of management and lookup tasks you can perform with this class. For more information and examples, follow the links to the reference page for each method or property. - -|To|Use| -|--------|---------| -|Add a namespace| method| -|Remove a namespace| method| -|Find the URI for the default namespace| property| -|Find the URI for a namespace prefix| method| -|Find the prefix for a namespace URI| method| -|Get a list of namespaces in the current node| method| -|Scope a namespace| and methods| -|Check whether a prefix is defined in the current scope| method| -|Get the name table used to look up prefixes and URIs| property| - - To add namespaces to the namespace manager, you create a object and then use the method. Default prefix and namespace pairs are automatically added to the namespace manager on creation. - - When you create the namespace manager, you can specify a name table from the , , or class, and then use the method to add the namespaces. - - You can supply the object as a parameter to the or method of the class to execute XPath query expressions that reference namespace-qualified element and attribute names. - - The namespace manager assumes that prefixes and namespaces have already been verified and conform to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) specification. The namespace manager does not perform any validation. - - The namespace manager atomizes the strings when they are added by using the method and when a lookup is performed by using the or method. - - The namespace manager implements enumeration support in addition to adding and retrieving namespaces. You can loop through the information saved in the namespace manager by using the `foreach` construct. For example, if you create a namespace manager with the name `nsmanager`, you can iterate through the table by using `foreach (String prefix in nsmanager)`. - - Because the namespace manager provides a string comparison with the prefix and namespaces as objects, there is a performance improvement when using the namespace manager over the direct comparison of a string. - - The following code example shows how to bind the prefix `xsd` with the namespace URI of and add it to the namespace manager: - -```vb -nsmgr.AddNamespace("xsd", "http://www.w3.org/2001/XMLSchema") -``` - -```csharp -nsmgr.AddNamespace("xsd", "http://www.w3.org/2001/XMLSchema"); -``` - - You can then find the namespace by using the method: - -```vb -nsmgr.LookupNamespace("xsd") -``` - -```csharp -nsmgr.LookupNamespace("xsd"); -``` - - The following example creates an by using the name table from an XML reader: - -```vb -Dim reader As New XmlTextReader("myfile.xml") -Dim nsmanager As New XmlNamespaceManager(reader.NameTable) -nsmanager.AddNamespace("msbooks", "www.microsoft.com/books") -nsmanager.PushScope() -nsmanager.AddNamespace("msstore", "www.microsoft.com/store") -While reader.Read() - Console.WriteLine("Reader Prefix:{0}", reader.Prefix) - Console.WriteLine("XmlNamespaceManager Prefix:{0}", - nsmanager.LookupPrefix(nsmanager.NameTable.Get(reader.NamespaceURI))) -End While -``` - -```csharp -XmlTextReader reader = new XmlTextReader("myfile.xml"); -XmlNamespaceManager nsmanager = new XmlNamespaceManager(reader.NameTable); -nsmanager.AddNamespace("msbooks", "www.microsoft.com/books"); -nsmanager.PushScope(); -nsmanager.AddNamespace("msstore", "www.microsoft.com/store"); -while (reader.Read()) -{ - Console.WriteLine("Reader Prefix:{0}", reader.Prefix); - Console.WriteLine("XmlNamespaceManager Prefix:{0}", - nsmanager.LookupPrefix(nsmanager.NameTable.Get(reader.NamespaceURI))); -} -``` - + stores prefixes and namespaces as strings. Here's a summary of management and lookup tasks you can perform with this class. For more information and examples, follow the links to the reference page for each method or property. + +|To|Use| +|--------|---------| +|Add a namespace| method| +|Remove a namespace| method| +|Find the URI for the default namespace| property| +|Find the URI for a namespace prefix| method| +|Find the prefix for a namespace URI| method| +|Get a list of namespaces in the current node| method| +|Scope a namespace| and methods| +|Check whether a prefix is defined in the current scope| method| +|Get the name table used to look up prefixes and URIs| property| + + To add namespaces to the namespace manager, you create a object and then use the method. Default prefix and namespace pairs are automatically added to the namespace manager on creation. + + When you create the namespace manager, you can specify a name table from the , , or class, and then use the method to add the namespaces. + + You can supply the object as a parameter to the or method of the class to execute XPath query expressions that reference namespace-qualified element and attribute names. + + The namespace manager assumes that prefixes and namespaces have already been verified and conform to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) specification. The namespace manager does not perform any validation. + + The namespace manager atomizes the strings when they are added by using the method and when a lookup is performed by using the or method. + + The namespace manager implements enumeration support in addition to adding and retrieving namespaces. You can loop through the information saved in the namespace manager by using the `foreach` construct. For example, if you create a namespace manager with the name `nsmanager`, you can iterate through the table by using `foreach (String prefix in nsmanager)`. + + Because the namespace manager provides a string comparison with the prefix and namespaces as objects, there is a performance improvement when using the namespace manager over the direct comparison of a string. + + The following code example shows how to bind the prefix `xsd` with the namespace URI of and add it to the namespace manager: + +```vb +nsmgr.AddNamespace("xsd", "http://www.w3.org/2001/XMLSchema") +``` + +```csharp +nsmgr.AddNamespace("xsd", "http://www.w3.org/2001/XMLSchema"); +``` + + You can then find the namespace by using the method: + +```vb +nsmgr.LookupNamespace("xsd") +``` + +```csharp +nsmgr.LookupNamespace("xsd"); +``` + + The following example creates an by using the name table from an XML reader: + +```vb +Dim reader As New XmlTextReader("myfile.xml") +Dim nsmanager As New XmlNamespaceManager(reader.NameTable) +nsmanager.AddNamespace("msbooks", "www.microsoft.com/books") +nsmanager.PushScope() +nsmanager.AddNamespace("msstore", "www.microsoft.com/store") +While reader.Read() + Console.WriteLine("Reader Prefix:{0}", reader.Prefix) + Console.WriteLine("XmlNamespaceManager Prefix:{0}", + nsmanager.LookupPrefix(nsmanager.NameTable.Get(reader.NamespaceURI))) +End While +``` + +```csharp +XmlTextReader reader = new XmlTextReader("myfile.xml"); +XmlNamespaceManager nsmanager = new XmlNamespaceManager(reader.NameTable); +nsmanager.AddNamespace("msbooks", "www.microsoft.com/books"); +nsmanager.PushScope(); +nsmanager.AddNamespace("msstore", "www.microsoft.com/store"); +while (reader.Read()) +{ + Console.WriteLine("Reader Prefix:{0}", reader.Prefix); + Console.WriteLine("XmlNamespaceManager Prefix:{0}", + nsmanager.LookupPrefix(nsmanager.NameTable.Get(reader.NamespaceURI))); +} +``` + ]]> XML Documents and Data @@ -197,25 +197,25 @@ while (reader.Read()) The to use. Initializes a new instance of the class with the specified . - object is used, after each read, any namespace and prefix strings pushed into the name table can be re-used by . - - For more information on atomized strings, see . - + object is used, after each read, any namespace and prefix strings pushed into the name table can be re-used by . + + For more information on atomized strings, see . + > [!NOTE] -> If you specify an existing name table, any namespaces in the name table are not automatically added to . You must use and to add or remove namespaces. - - - -## Examples - The following example creates an using the name table of the reader. - +> If you specify an existing name table, any namespaces in the name table are not automatically added to . You must use and to add or remove namespaces. + + + +## Examples + The following example creates an using the name table of the reader. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNamespaceManager.XmlNamespaceManager Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.XmlNamespaceManager Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.XmlNamespaceManager Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -274,37 +274,37 @@ while (reader.Read()) - The prefix to associate with the namespace being added. Use String.Empty to add a default namespace. - + The prefix to associate with the namespace being added. Use String.Empty to add a default namespace. + **Note** If the will be used for resolving namespaces in an XML Path Language (XPath) expression, a prefix must be specified. If an XPath expression does not include a prefix, it is assumed that the namespace Uniform Resource Identifier (URI) is the empty namespace. For more information about XPath expressions and the , refer to the and methods. The namespace to add. Adds the given namespace to the collection. - does not check `prefix` and `uri` for conformance. - - checks names, including prefixes and namespaces, to ensure they are valid XML names according to the World Wide Web Consortium (W3C) [Namespaces specification](https://www.w3.org/TR/REC-xml-names/). is used internally by , so to avoid a duplication of efforts, assumes all prefixes and namespaces are valid. - - If the prefix and namespace already exist within the current scope, the new prefix and namespace pair will replace the existing prefix/namespace combination. The same prefix and namespace combination can exist across different scopes. - - The following prefix/namespace pairs are added by default to the . They can be determined at any scope. - -|Prefix|Namespace| -|------------|---------------| -|xmlns| (the xmlns prefix namespace)| -|xml| (the XML namespace)| -|String.Empty|String.Empty (the empty namespace). This value can be reassigned a different prefix. For example, xmlns="" defines the default namespace to be the empty namespace| - - - -## Examples - The following example uses to resolve namespaces in an XML fragment. - + does not check `prefix` and `uri` for conformance. + + checks names, including prefixes and namespaces, to ensure they are valid XML names according to the World Wide Web Consortium (W3C) [Namespaces specification](https://www.w3.org/TR/REC-xml-names/). is used internally by , so to avoid a duplication of efforts, assumes all prefixes and namespaces are valid. + + If the prefix and namespace already exist within the current scope, the new prefix and namespace pair will replace the existing prefix/namespace combination. The same prefix and namespace combination can exist across different scopes. + + The following prefix/namespace pairs are added by default to the . They can be determined at any scope. + +|Prefix|Namespace| +|------------|---------------| +|xmlns| (the xmlns prefix namespace)| +|xml| (the XML namespace)| +|String.Empty|String.Empty (the empty namespace). This value can be reassigned a different prefix. For example, xmlns="" defines the default namespace to be the empty namespace| + + + +## Examples + The following example uses to resolve namespaces in an XML fragment. + :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/AddNamespace/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.AddNamespace Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.AddNamespace Example/VB/source.vb" id="Snippet1"::: + ]]> The value for is "xml" or "xmlns". @@ -356,20 +356,20 @@ while (reader.Read()) Gets the namespace URI for the default namespace. The namespace URI for the default namespace, or an empty string if there is no default namespace. - @@ -423,20 +423,20 @@ while (reader.Read()) Returns an enumerator to use to iterate through the namespaces in the . An containing the prefixes stored by the . - to view all the namespace pairs stored in the object. - -```vb -Dim nsEnum As IEnumerator = nsmgr.GetEnumerator() -Do While nsEnum.MoveNext - If nsEnum.Current <> "" Then - MsgBox("xmlns:" + nsEnum.Current + "=" + nsmgr.LookupNamespace(nsEnum.Current)) - End If -Loop -``` - + to view all the namespace pairs stored in the object. + +```vb +Dim nsEnum As IEnumerator = nsmgr.GetEnumerator() +Do While nsEnum.MoveNext + If nsEnum.Current <> "" Then + MsgBox("xmlns:" + nsEnum.Current + "=" + nsmgr.LookupNamespace(nsEnum.Current)) + End If +Loop +``` + ]]> XML Documents and Data @@ -488,22 +488,22 @@ Loop An enumeration value that specifies the type of namespace nodes to return. - Gets a collection of namespace names keyed by prefix which can be used to enumerate the namespaces currently in scope. + Gets a collection of namespace names keyed by prefix, which can be used to enumerate the namespaces currently in scope. A collection of namespace and prefix pairs currently in scope. - values affect the namespaces returned by the method. - -|XmlNamespaceScope value|xmlns:xml|xmlns:xmlns|xmlns=""| -|-----------------------------|---------------|-----------------|---------------| -|`All`|Yes|No|No| -|`ExcludeXml`|No|No|No| -|`Local`|No|No|Yes| - + values affect the namespaces returned by the method. + +|XmlNamespaceScope value|xmlns:xml|xmlns:xmlns|xmlns=""| +|-----------------------------|---------------|-----------------|---------------| +|`All`|Yes|No|No| +|`ExcludeXml`|No|No|No| +|`Local`|No|No|Yes| + ]]> XML Documents and Data @@ -557,23 +557,23 @@ Loop if there is a namespace defined; otherwise, . - [!NOTE] -> xmlns:x= "" is illegal according to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) recommendation. - - - -## Examples - The following example displays the default namespace, if one exists. - +> xmlns:x= "" is illegal according to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) recommendation. + + + +## Examples + The following example displays the default namespace, if one exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNamespaceManager.DefaultNamespace Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/DefaultNamespace/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.DefaultNamespace Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.DefaultNamespace Example/VB/source.vb" id="Snippet1"::: + ]]> XML Documents and Data @@ -628,19 +628,19 @@ Loop The prefix whose namespace URI you want to resolve. To match the default namespace, pass String.Empty. Gets the namespace URI for the specified prefix. - The namespace URI for or if there is no mapped namespace. The returned string is atomized. - + The namespace URI for or if there is no mapped namespace. The returned string is atomized. + For more information on atomized strings, see the class. - , and then displays all the pairs in the collection. - + , and then displays all the pairs in the collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/LookupNamespace/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -705,53 +705,53 @@ Loop Finds the prefix declared for the given namespace URI. The matching prefix. If there is no mapped prefix, the method returns String.Empty. If a null value is supplied, then is returned. - ). - - The returned string is also atomized. For more information on atomized strings, see the class. - - - -## Examples - The following example shows how to use the method when writing an attribute. It uses the method to start the attribute, looks up the prefix for the `urn:samples` namespace URI, and then uses that prefix in the when writing the `ISBN` attribute: - -```vb -Dim prefix As String = nsMgr.LookupPrefix("urn:samples") -writer.WriteStartAttribute(prefix, "ISBN", "urn:samples") - -``` - -```csharp -XmlNameTable nt = new XmlNameTable(); -XmlNamespaceManager nsMgr = new XmlNamespaceManager(nt); -nsMgr.AddNamespace("bk","urn:samples");string prefix = writer nsMgr.LookupPrefix("urn:samples"); -writer.WriteStartAttribute(prefix, "ISBN", "urn:samples"); -``` - - The following example uses to find the prefix defined on an element. - -```vb -writer.WriteStartElement("root", "book") -writer.WriteStartElement("x", "node", "author") -s = writer.LookupPrefix("author") -CError.Compare(s, "x", "Error in nested element") -writer.WriteEndElement() -s = writer.LookupPrefix("book") -CError.Compare(s, Nothing, "Error in root element") -writer.WriteEndElement() - -``` - - **Output** - -``` - - - -``` - + ). + + The returned string is also atomized. For more information on atomized strings, see the class. + + + +## Examples + The following example shows how to use the method when writing an attribute. It uses the method to start the attribute, looks up the prefix for the `urn:samples` namespace URI, and then uses that prefix in the when writing the `ISBN` attribute: + +```vb +Dim prefix As String = nsMgr.LookupPrefix("urn:samples") +writer.WriteStartAttribute(prefix, "ISBN", "urn:samples") + +``` + +```csharp +XmlNameTable nt = new XmlNameTable(); +XmlNamespaceManager nsMgr = new XmlNamespaceManager(nt); +nsMgr.AddNamespace("bk","urn:samples");string prefix = writer nsMgr.LookupPrefix("urn:samples"); +writer.WriteStartAttribute(prefix, "ISBN", "urn:samples"); +``` + + The following example uses to find the prefix defined on an element. + +```vb +writer.WriteStartElement("root", "book") +writer.WriteStartElement("x", "node", "author") +s = writer.LookupPrefix("author") +CError.Compare(s, "x", "Error in nested element") +writer.WriteEndElement() +s = writer.LookupPrefix("book") +CError.Compare(s, Nothing, "Error in root element") +writer.WriteEndElement() + +``` + + **Output** + +``` + + + +``` + ]]> @@ -815,11 +815,11 @@ writer.WriteEndElement() Gets the associated with this object. The used by this object. - @@ -871,20 +871,20 @@ writer.WriteEndElement() if there are namespace scopes left on the stack; if there are no more namespaces to pop. - (by calling ) since the last call to are removed. - - - -## Examples - The following example adds prefix/namespace pairs to the and then displays all the pairs in the collection. - + (by calling ) since the last call to are removed. + + + +## Examples + The following example adds prefix/namespace pairs to the and then displays all the pairs in the collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/LookupNamespace/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -934,20 +934,20 @@ writer.WriteEndElement() Pushes a namespace scope onto the stack. - (by calling ), belong to the pushed namespace scope. - - - -## Examples - The following example adds prefix/namespace pairs to the and then displays all the pairs in the collection. - + (by calling ), belong to the pushed namespace scope. + + + +## Examples + The following example adds prefix/namespace pairs to the and then displays all the pairs in the collection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNamespaceManager/LookupNamespace/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNamespaceManager.PopScope Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml/XmlNamespaceScope.xml b/xml/System.Xml/XmlNamespaceScope.xml index 0081b400b54..b2e9ce4cbae 100644 --- a/xml/System.Xml/XmlNamespaceScope.xml +++ b/xml/System.Xml/XmlNamespaceScope.xml @@ -87,7 +87,7 @@ 0 - All namespaces defined in the scope of the current node. This includes the xmlns:xml namespace which is always declared implicitly. The order of the namespaces returned is not defined. + All namespaces defined in the scope of the current node. This includes the xmlns:xml namespace, which is always declared implicitly. The order of the namespaces returned is not defined. diff --git a/xml/System.Xml/XmlNode.xml b/xml/System.Xml/XmlNode.xml index 24d49eb039b..7c8f7937eb1 100644 --- a/xml/System.Xml/XmlNode.xml +++ b/xml/System.Xml/XmlNode.xml @@ -2948,7 +2948,7 @@ d. as its argument. The `XmlNamespaceManager` is used to resolve namespaces. + If the XPath expression requires namespace resolution, you must use the `SelectNodes` overload that takes an as its argument. The `XmlNamespaceManager` is used to resolve namespaces. > [!NOTE] > If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). @@ -3118,7 +3118,7 @@ nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) ]]> - The XPath expression contains a prefix which is not defined in the . + The XPath expression contains a prefix that's not defined in the . XPath Selections and Custom Functions, and More W3C XPath 1.0 recommendation @@ -3215,7 +3215,7 @@ nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) as its argument. The `XmlNamespaceManager` is used to resolve namespaces. + If the XPath expression requires namespace resolution, you must use the `SelectSingleNode` overload that takes an as its argument. The `XmlNamespaceManager` is used to resolve namespaces. > [!NOTE] > If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get a selected node. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). @@ -3381,7 +3381,7 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) ]]> - The XPath expression contains a prefix which is not defined in the . + The XPath expression contains a prefix that's not defined in the . XPath Selections and Custom Functions, and More W3C XPath 1.0 recommendation diff --git a/xml/System.Xml/XmlNodeReader.xml b/xml/System.Xml/XmlNodeReader.xml index 836011a8bb0..1bb11b42eb1 100644 --- a/xml/System.Xml/XmlNodeReader.xml +++ b/xml/System.Xml/XmlNodeReader.xml @@ -892,7 +892,7 @@ String dt4 = reader.GetAttribute("dt",http://www.w3.org/2000/xmlns/); ## Examples - The following example displays the value for every node which can have a value. + The following example displays the value for every node that can have a value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNodeReader.HasValue Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNodeReader/HasValue/source.cs" id="Snippet1"::: diff --git a/xml/System.Xml/XmlReaderSettings.xml b/xml/System.Xml/XmlReaderSettings.xml index 7305cade3ed..ab3dc214f6f 100644 --- a/xml/System.Xml/XmlReaderSettings.xml +++ b/xml/System.Xml/XmlReaderSettings.xml @@ -467,7 +467,7 @@ If the is processing text data, it always checks tha System.Xml.ConformanceLevel - Gets or sets the level of conformance which the will comply. + Gets or sets the level of conformance with which the will comply. One of the enumeration values that specifies the level of conformance that the XML reader will enforce. The default is . method uses the specified by the property.