diff --git a/xml/Microsoft.Build.Tasks.Windows/GenerateTemporaryTargetAssembly.xml b/xml/Microsoft.Build.Tasks.Windows/GenerateTemporaryTargetAssembly.xml index 6dcb2553f17..cf924a43105 100644 --- a/xml/Microsoft.Build.Tasks.Windows/GenerateTemporaryTargetAssembly.xml +++ b/xml/Microsoft.Build.Tasks.Windows/GenerateTemporaryTargetAssembly.xml @@ -107,8 +107,8 @@ System.String - Gets or sets the MS Build target name which is used to generate assembly from source code files. - The MS Build target name which is used to generate assembly from source code files. + Gets or sets the MSBuild target name that's used to generate assembly from source code files. + The MSBuild target name that's used to generate assembly from source code files. To be added. @@ -144,8 +144,8 @@ System.String - Gets or sets the appropriate item name which can be accepted by managed compiler task. - The appropriate item name which can be accepted by managed compiler task. + Gets or sets the appropriate item name that can be accepted by managed compiler task. + The appropriate item name that can be accepted by managed compiler task. To be added. @@ -414,8 +414,8 @@ System.String - Gets or sets the item name which is used to keep the Reference list in managed compiler task. - The item name which is used to keep the Reference list in managed compiler task. + Gets or sets the item name that's used to keep the Reference list in managed compiler task. + The item name that's used to keep the Reference list in managed compiler task. To be added. diff --git a/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass1.xml b/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass1.xml index b0e1a626266..a26055e4878 100644 --- a/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass1.xml +++ b/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass1.xml @@ -107,11 +107,11 @@ to run the compilation in second application domain; otherwise, . - @@ -215,7 +215,7 @@ Gets or sets the short name of assembly that will be generated for this project. - The short name of assembly which will be generated for this project. + The short name of assembly that will be generated for this project. To be added. diff --git a/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass2.xml b/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass2.xml index 7b990665ad2..7b12ecf29d5 100644 --- a/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass2.xml +++ b/xml/Microsoft.Build.Tasks.Windows/MarkupCompilePass2.xml @@ -138,7 +138,7 @@ Gets or sets the short name of assembly that will be generated for this project. - The short name of assembly which will be generated for this project. + The short name of assembly that will be generated for this project. To be added. diff --git a/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml b/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml index 3971fee6eb6..e33b1593cf5 100644 --- a/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml +++ b/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml @@ -34,46 +34,46 @@ Provides properties and methods for working with drives, files, and directories. - |[How to: Read Text from Files with a StreamReader](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| -|Write to a text file|[How to: Write Text to Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| -|Append to a text file|[How to: Append to Text Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| -|Write to a binary file|[How to: Write to Binary Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files)| -|Write to text files in the **MyDocuments** directory|[How to: Write Text to Files in the My Documents Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory)| -|Write to a text file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| -|Copy files with a specific pattern|[How to: Copy Files with a Specific Pattern to a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory)| -|Copy a file to the same directory|[How to: Create a Copy of a File in the Same Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory)| -|Copy a file to a different directory|[How to: Create a Copy of a File in a Different Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory)| -|Create a file|[How to: Create a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file)| -|Delete a file|[How to: Delete a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-delete-a-file)| -|Find files with a specific pattern|[How to: Find Files with a Specific Pattern](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern)| -|Move a file|[How to: Move a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file)| -|Rename a file|[How to: Rename a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file)| -|Copy a directory to another directory|[How to: Copy a Directory to Another Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| -|Create a directory|[How to: Create a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory)| -|Find subdirectories with a specific pattern|[How to: Find Subdirectories with a Specific Pattern](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern)| -|Get the collection of files in a directory|[How to: Get the Collection of Files in a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory)| -|Read from the **MyDocuments** directory|[How to: Retrieve the Contents of the My Documents Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory)| -|Parse a file path|[How to: Parse File Paths](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths)| - - - -## Examples - This example checks to determine whether the folder `C:\backup\logs` exists and checks its properties. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet23"::: - + |[How to: Read Text from Files with a StreamReader](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| +|Write to a text file|[How to: Write Text to Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| +|Append to a text file|[How to: Append to Text Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| +|Write to a binary file|[How to: Write to Binary Files](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files)| +|Write to text files in the **MyDocuments** directory|[How to: Write Text to Files in the My Documents Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory)| +|Write to a text file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| +|Copy files with a specific pattern|[How to: Copy Files with a Specific Pattern to a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory)| +|Copy a file to the same directory|[How to: Create a Copy of a File in the Same Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory)| +|Copy a file to a different directory|[How to: Create a Copy of a File in a Different Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory)| +|Create a file|[How to: Create a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file)| +|Delete a file|[How to: Delete a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-delete-a-file)| +|Find files with a specific pattern|[How to: Find Files with a Specific Pattern](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern)| +|Move a file|[How to: Move a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file)| +|Rename a file|[How to: Rename a File](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file)| +|Copy a directory to another directory|[How to: Copy a Directory to Another Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| +|Create a directory|[How to: Create a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory)| +|Find subdirectories with a specific pattern|[How to: Find Subdirectories with a Specific Pattern](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern)| +|Get the collection of files in a directory|[How to: Get the Collection of Files in a Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory)| +|Read from the **MyDocuments** directory|[How to: Retrieve the Contents of the My Documents Directory](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory)| +|Parse a file path|[How to: Parse File Paths](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths)| + + + +## Examples + This example checks to determine whether the folder `C:\backup\logs` exists and checks its properties. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet23"::: + ]]> @@ -114,11 +114,11 @@ Initializes a new instance of the class. - @@ -171,30 +171,30 @@ Combines two paths and returns a properly formatted path. The combination of the specified paths. - @@ -254,28 +254,28 @@ The location to which the directory contents should be copied. Copies the contents of a directory to another directory. - in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. - - The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. - -|To|See| -|-|-| -|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| - - - -## Examples - The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet94"::: - - Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. - + in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. + + The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. + +|To|See| +|-|-| +|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| + + + +## Examples + The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet94"::: + + Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -330,28 +330,28 @@ Whether to visually track the operation's progress. Default is . Copies the contents of a directory to another directory. - in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. - - The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. - -|To|See| -|-|-| -|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| - - - -## Examples - The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, showing progress dialog and any error dialog. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet92"::: - - Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. - + in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. + + The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. + +|To|See| +|-|-| +|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| + + + +## Examples + The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, showing progress dialog and any error dialog. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet92"::: + + Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -415,28 +415,28 @@ to overwrite existing files; otherwise . Default is . Copies the contents of a directory to another directory. - in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. - - The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. - -|To|See| -|-|-| -|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| - - - -## Examples - The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, overwriting existing files. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet49"::: - - Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. - + in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. + + The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. + +|To|See| +|-|-| +|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| + + + +## Examples + The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, overwriting existing files. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet49"::: + + Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -493,28 +493,28 @@ Specifies what should be done if the user clicks **Cancel** during the operation. Default is . Copies the contents of a directory to another directory. - in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. - - The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. - -|To|See| -|-|-| -|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| - - - -## Examples - The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, showing progress dialog and any error dialog, and does nothing if the user clicks **Cancel** during the operation. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet93"::: - - Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. - + in which the file or directory path is the key and the specific exception message is contained in the corresponding value. Use `For…Each` to enumerate through the entries. + + The following table lists an example of a task involving the `My.Computer.FileSystem.CopyDirectory` method. + +|To|See| +|-|-| +|Copy a directory|[How to: Copy a Directory to Another Directory in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory)| + + + +## Examples + The following example copies the contents of directory `TestDirectory1` into `TestDirectory2`, showing progress dialog and any error dialog, and does nothing if the user clicks **Cancel** during the operation. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet93"::: + + Replace `C:\TestDirectory1` and `C:\TestDirectory2` with the path and name of the directory you wish to copy and the location to which you wish to copy it. + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -584,33 +584,33 @@ The location to which the file should be copied. Copies a file to a new location. - @@ -665,33 +665,33 @@ Whether to visually track the operation's progress. Default is . Copies a file to a new location. - @@ -753,33 +753,33 @@ if existing files should be overwritten; otherwise . Default is . Copies a file to a new location. - @@ -836,33 +836,33 @@ Specifies what should be done if the user clicks **Cancel** during the operation. Default is . Copies a file to a new location. - @@ -915,24 +915,24 @@ Name and location of the directory. Creates a directory. - The directory name is malformed. For example, it contains illegal characters or is only white space. @@ -976,22 +976,22 @@ Gets or sets the current directory. The current directory for file I/O operations. - The path is not valid. @@ -1050,25 +1050,25 @@ Specifies what should be done when a directory that is to be deleted contains files or directories. Default is . Deletes a directory. - The path is a zero-length string, is malformed, contains only white space, or contains invalid characters (including wildcard characters). The path is a device path (starts with \\\\.\\). @@ -1122,30 +1122,30 @@ Specifies whether or not the deleted file should be sent to the **Recycle Bin**. Default is . Deletes a directory. - The path is a zero-length string, is malformed, contains only white space, or contains invalid characters (including wildcard characters). The path is a device path (starts with \\\\.\\). @@ -1202,30 +1202,30 @@ Specifies whether to throw an exception if the user clicks **Cancel**. Deletes a directory. - The path is a zero-length string, is malformed, contains only white space, or contains invalid characters (including wildcard characters). The path is a device path (starts with \\\\.\\). @@ -1292,30 +1292,30 @@ Name and path of the file to be deleted. Deletes a file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; it has a trailing slash where a file must be specified; or it is a device path (starts with \\\\.\\). @@ -1368,32 +1368,32 @@ Whether or not the deleted file should be sent to the **Recycle Bin**. Default is . Deletes a file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; it has a trailing slash where a file must be specified; or it is a device path (starts with \\\\.\\). @@ -1450,32 +1450,32 @@ Specifies whether or not an exception is thrown when the user cancels the operation. Default is . Deletes a file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; it has a trailing slash where a file must be specified; or it is a device path (starts with \\\\.\\). @@ -1530,13 +1530,13 @@ if the directory exists; otherwise . This method also returns if the parameter represents the name and path of a file rather than a directory. - @@ -1572,18 +1572,18 @@ Returns a read-only collection of all available drive names. A read-only collection of all available drives as objects. - @@ -1626,18 +1626,18 @@ Returns if the specified file exists. Returns if the file exists; otherwise this method returns . This method also returns if the parameter represents the path of a directory rather than a file. - The name of the file ends with a backslash (\\). @@ -1701,26 +1701,26 @@ Returns a read-only collection of strings representing the names of files containing the specified text. Read-only collection of the names of files containing the specified text. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\.\). @@ -1788,26 +1788,26 @@ Returns a read-only collection of strings representing the names of files containing the specified text. Read-only collection of the names of files containing the specified text. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\.\). @@ -1874,24 +1874,24 @@ Returns a collection of strings representing the path names of subdirectories within a directory. Read-only collection of the path names of subdirectories within the specified directory. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -1960,28 +1960,28 @@ Returns a collection of strings representing the path names of subdirectories within a directory. Read-only collection of the path names of subdirectories within the specified directory. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2034,18 +2034,18 @@ object for the specified path. - object is accessed. - - - -## Examples - This example gets a object for the directory `C:\Documents and Settings` and displays the directory's creation time, last access time, and last write time. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet7"::: - + object is accessed. + + + +## Examples + This example gets a object for the directory `C:\Documents and Settings` and displays the directory's creation time, last access time, and last write time. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet7"::: + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2094,20 +2094,20 @@ object for the specified drive. - class models a drive and provides methods and properties to query for drive information. Use to determine what drives are available, and what type of drives they are. You can also query the property to determine the capacity and available free space on the drive. - - - -## Examples - This example obtains a object for the C drive and uses it to display information about the drive. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet11"::: - - For information on the different drive types, see . - + class models a drive and provides methods and properties to query for drive information. Use to determine what drives are available, and what type of drives they are. You can also query the property to determine the capacity and available free space on the drive. + + + +## Examples + This example obtains a object for the C drive and uses it to display information about the drive. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet11"::: + + For information on the different drive types, see . + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2156,24 +2156,24 @@ object for the specified file. - object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet1"::: - + object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet1"::: + ]]> The path name is malformed. For example, it contains invalid characters or is only white space. The file name has a trailing slash mark. @@ -2237,33 +2237,33 @@ Returns a read-only collection of strings representing the names of files within a directory. Read-only collection of file names from the specified directory. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2332,33 +2332,33 @@ Returns a read-only collection of strings representing the names of files within a directory. Read-only collection of file names from the specified directory. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2411,28 +2411,28 @@ Parses the file name out of the path provided. The file name from the specified path. - @@ -2473,18 +2473,18 @@ Returns the parent path of the provided path. The parent path of the provided path. - Path does not have a parent path because it is a root path. @@ -2528,18 +2528,18 @@ containing the full path of the temporary file. - @@ -2596,22 +2596,22 @@ Path of the directory to which the source directory is being moved. Moves a directory from one location to another. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2667,22 +2667,22 @@ Specifies whether to visually track the operation's progress. Default is . Moves a directory from one location to another. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2746,22 +2746,22 @@ if existing directories should be overwritten; otherwise . Default is . Moves a directory from one location to another. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2819,22 +2819,22 @@ Specifies whether or not an exception is thrown when the user cancels the operation. Default is . Moves a directory from one location to another. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\). @@ -2908,30 +2908,30 @@ Path of the directory into which the file should be moved. Moves a file to a new location. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -2983,30 +2983,30 @@ Specifies whether to visually track the operation's progress. Default is . Moves a file to a new location. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3066,30 +3066,30 @@ to overwrite existing files; otherwise . Default is . Moves a file to a new location. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3143,30 +3143,30 @@ Specifies whether or not an exception is thrown when the user cancels the operation. Default is . Moves a file to a new location. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3225,28 +3225,28 @@ The file to be opened with the . - The method allows you to create a object, which provides a way to easily and efficiently parse structured text files, such as logs. The object can be used to read both delimited and fixed-width files. + The method allows you to create a object, which provides a way to easily and efficiently parse structured text files, such as logs. The object can be used to read both delimited and fixed-width files. to read the specified file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3307,24 +3307,24 @@ to read the specified file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3385,24 +3385,24 @@ to read the specified file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3463,24 +3463,24 @@ object to read from the file. - . - - The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileReader` method. - -|To|See| -|-|-| -|Open a file with a |[How to: Read Text from Files with a StreamReader (Visual Basic)](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| - - - -## Examples - This example opens the file `Testfile.txt`, reads a line from it, and displays the line in a `MessageBox`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet2"::: - + . + + The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileReader` method. + +|To|See| +|-|-| +|Open a file with a |[How to: Read Text from Files with a StreamReader (Visual Basic)](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| + + + +## Examples + This example opens the file `Testfile.txt`, reads a line from it, and displays the line in a `MessageBox`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet2"::: + ]]> The file name ends with a backslash (\\). @@ -3529,24 +3529,24 @@ object to read from the file. - . - - The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileReader` method. - -|To|See| -|-|-| -|Open a file with a |[How to: Read Text from Files with a StreamReader (Visual Basic)](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| - - - -## Examples - This example opens the file `Testfile.txt`, reads a line from it, and displays the line in a `MessageBox`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet2"::: - + . + + The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileReader` method. + +|To|See| +|-|-| +|Open a file with a |[How to: Read Text from Files with a StreamReader (Visual Basic)](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader)| + + + +## Examples + This example opens the file `Testfile.txt`, reads a line from it, and displays the line in a `MessageBox`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet2"::: + ]]> The file name ends with a backslash (\\). @@ -3605,29 +3605,29 @@ object to write to the specified file. - object for that stream. You can write to the steam as many times as necessary and then close it when you are finished. - + object for that stream. You can write to the steam as many times as necessary and then close it when you are finished. + > [!NOTE] -> You must call the method on the object to make sure that all data is correctly written to the underlying stream. - - If you are writing only a few strings to a file, it might be simpler to use the method. - - The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileWriter` method. - -|To|See| -|-|-| -|Write text to a file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| - - - -## Examples - This example opens a with the `My.Computer.FileSystem.OpenTextFileWriter` method and uses it to write a string to a text file with the `WriteLine` method of the `StreamWriter` class. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet14"::: - +> You must call the method on the object to make sure that all data is correctly written to the underlying stream. + + If you are writing only a few strings to a file, it might be simpler to use the method. + + The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileWriter` method. + +|To|See| +|-|-| +|Write text to a file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| + + + +## Examples + This example opens a with the `My.Computer.FileSystem.OpenTextFileWriter` method and uses it to write a string to a text file with the `WriteLine` method of the `StreamWriter` class. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet14"::: + ]]> @@ -3679,29 +3679,29 @@ object to write to the specified file. - object for that stream. You can write to the steam as many times as necessary and then close it when you are finished. - + object for that stream. You can write to the steam as many times as necessary and then close it when you are finished. + > [!NOTE] -> You must call the method on the object to make sure that all data is correctly written to the underlying stream. - - If you are writing only a few strings to a file, it might be simpler to use the method. - - The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileWriter` method. - -|To|See| -|-|-| -|Write text to a file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| - - - -## Examples - This example opens a with the `My.Computer.FileSystem.OpenTextFileWriter` method with `Unicode` encoding and uses it to write a string to a text file with the `WriteLine` method of the `StreamWriter` class. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet23"::: - +> You must call the method on the object to make sure that all data is correctly written to the underlying stream. + + If you are writing only a few strings to a file, it might be simpler to use the method. + + The following table lists an example of a task involving the `My.Computer.FileSystem.OpenTextFileWriter` method. + +|To|See| +|-|-| +|Write text to a file with a `StreamWriter`|[How to: Write Text to Files with a StreamWriter in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter)| + + + +## Examples + This example opens a with the `My.Computer.FileSystem.OpenTextFileWriter` method with `Unicode` encoding and uses it to write a string to a text file with the `WriteLine` method of the `StreamWriter` class. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet23"::: + ]]> @@ -3748,26 +3748,26 @@ array containing the contents of the file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3827,32 +3827,32 @@ containing the contents of the file. - method. - - Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. Verify all inputs before using the data in your application. - - The following table lists an example of a task involving the `My.Computer.FileSystem.ReadAllText` method. - -|To|See| -|-|-| -|Read from a text file|[How to: Read From Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files)| - - - -## Examples - This example reads the contents of `Test.txt` into a string and then displays it in a message box. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet8"::: - - This example reads the contents of the ASCII file `Test.txt` into a string and then displays it in a message box. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet9"::: - + method. + + Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. Verify all inputs before using the data in your application. + + The following table lists an example of a task involving the `My.Computer.FileSystem.ReadAllText` method. + +|To|See| +|-|-| +|Read from a text file|[How to: Read From Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files)| + + + +## Examples + This example reads the contents of `Test.txt` into a string and then displays it in a message box. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet8"::: + + This example reads the contents of the ASCII file `Test.txt` into a string and then displays it in a message box. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet9"::: + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3908,32 +3908,32 @@ containing the contents of the file. - The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -3986,27 +3986,27 @@ New name for directory. Renames a directory. - contains path information. - is . - - -or- - + is . + + -or- + is or an empty string. The directory does not exist. There is an existing file or directory with the name specified in . @@ -4054,35 +4054,35 @@ New name of file. Renames a file. - method to move and rename the file. - - The following table lists an example of a task involving the `My.Computer.FileSystem.RenameFile` method. - -|To|See| -|-|-| -|Rename a file|[How to: Rename a File in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file)| - - - -## Examples - This example renames the file `Test.txt` to `SecondTest.txt`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet1"::: - - Change "`C:\Test.txt`" to the path and file name of the file that you want to rename. - + method to move and rename the file. + + The following table lists an example of a task involving the `My.Computer.FileSystem.RenameFile` method. + +|To|See| +|-|-| +|Rename a file|[How to: Rename a File in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file)| + + + +## Examples + This example renames the file `Test.txt` to `SecondTest.txt`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet1"::: + + Change "`C:\Test.txt`" to the path and file name of the file that you want to rename. + ]]> contains path information or ends with a backslash (\\). - is . - - -or- - + is . + + -or- + is or an empty string. The directory does not exist. There is an existing file or directory with the name specified in . @@ -4132,27 +4132,27 @@ to append to the file contents; to overwrite the file contents. Default is . Writes data to a binary file. - exception will be thrown. If the path is valid but the file does not exist, the file is created. - + exception will be thrown. If the path is valid but the file does not exist, the file is created. + > [!NOTE] -> The `WriteAllBytes` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllBytes` method is simpler than code that uses a object. However, if you are adding data to a file using a loop, a object can provide better performance because you only have to open and close the file once. - - The following table lists an example of a task involving the `My.Computer.FileSystem.WriteAllBytes` method. - -|To|See| -|-|-| -|Write to a binary file|[How to: Write to Binary Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files)| - - - -## Examples - This example appends the data array `CustomerData` to the file `CollectedData`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet50"::: - +> The `WriteAllBytes` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllBytes` method is simpler than code that uses a object. However, if you are adding data to a file using a loop, a object can provide better performance because you only have to open and close the file once. + + The following table lists an example of a task involving the `My.Computer.FileSystem.WriteAllBytes` method. + +|To|See| +|-|-| +|Write to a binary file|[How to: Write to Binary Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files)| + + + +## Examples + This example appends the data array `CustomerData` to the file `CollectedData`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb" id="Snippet50"::: + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -4215,36 +4215,36 @@ to append to the contents of the file; to overwrite the contents of the file. Writes text to a file. - method. - - If the specified file does not exist, it is created. - - If the specified encoding does not match the existing encoding of the file, the specified coding is ignored. - + method. + + If the specified file does not exist, it is created. + + If the specified encoding does not match the existing encoding of the file, the specified coding is ignored. + > [!NOTE] -> The `WriteAllText` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllText` method is simpler than code that uses a object. However, if you are adding strings to a file by using a loop, a object can provide better performance because you only have to open and close the file one time. For more information, see the method. - - The following table lists examples of tasks involving the `My.Computer.FileSystem.WriteAllText` method. - -|To|See| -|-|-| -|Write text to a file|[How to: Write Text to Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| -|Append text to a file|[How to: Append to Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| - - - -## Examples - This example writes the line `"This is new text to be added."` to the file `Test.txt`, overwriting any existing text in the file. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet21"::: - - This example writes the names of the files in the `Documents and Settings` folder to `FileList.txt`, inserting a carriage return between each for better readability. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet22"::: - +> The `WriteAllText` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllText` method is simpler than code that uses a object. However, if you are adding strings to a file by using a loop, a object can provide better performance because you only have to open and close the file one time. For more information, see the method. + + The following table lists examples of tasks involving the `My.Computer.FileSystem.WriteAllText` method. + +|To|See| +|-|-| +|Write text to a file|[How to: Write Text to Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| +|Append text to a file|[How to: Append to Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| + + + +## Examples + This example writes the line `"This is new text to be added."` to the file `Test.txt`, overwriting any existing text in the file. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet21"::: + + This example writes the names of the files in the `Documents and Settings` folder to `FileList.txt`, inserting a carriage return between each for better readability. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet22"::: + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. @@ -4302,34 +4302,34 @@ What encoding to use when writing to file. Writes text to a file. - [!NOTE] -> The `WriteAllText` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllText` method is simpler than code that uses a object. However, if you are adding strings to a file by using a loop, a object can provide better performance because you only have to open and close the file one time. For more information, see the method. - - The following table lists examples of tasks involving the `My.Computer.FileSystem.WriteAllText` method. - -|To|See| -|-|-| -|Write text to a file|[How to: Write Text to Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| -|Append text to a file|[How to: Append to Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| - - - -## Examples - This example writes the line `"This is new text to be added."` to the file `Test.txt`, overwriting any existing text in the file. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet21"::: - - This example writes the names of the files in the `Documents and Settings` folder to `FileList.txt`, inserting a carriage return between each for better readability. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet22"::: - +> The `WriteAllText` method opens a file, writes to it, and then closes it. Code that uses the `WriteAllText` method is simpler than code that uses a object. However, if you are adding strings to a file by using a loop, a object can provide better performance because you only have to open and close the file one time. For more information, see the method. + + The following table lists examples of tasks involving the `My.Computer.FileSystem.WriteAllText` method. + +|To|See| +|-|-| +|Write text to a file|[How to: Write Text to Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files)| +|Append text to a file|[How to: Append to Text Files in Visual Basic](/dotnet/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files)| + + + +## Examples + This example writes the line `"This is new text to be added."` to the file `Test.txt`, overwriting any existing text in the file. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet21"::: + + This example writes the names of the files in the `Documents and Settings` folder to `FileList.txt`, inserting a carriage return between each for better readability. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb" id="Snippet22"::: + ]]> The path is not valid for one of the following reasons: it is a zero-length string; it contains only white space; it contains invalid characters; or it is a device path (starts with \\\\.\\); it ends with a trailing slash. diff --git a/xml/Microsoft.VisualBasic.MyServices/RegistryProxy.xml b/xml/Microsoft.VisualBasic.MyServices/RegistryProxy.xml index 7d766329c08..8b2ae1e7c62 100644 --- a/xml/Microsoft.VisualBasic.MyServices/RegistryProxy.xml +++ b/xml/Microsoft.VisualBasic.MyServices/RegistryProxy.xml @@ -36,26 +36,26 @@ Provides properties and methods for manipulating the registry. - enumeration. Any code running with full trust (under the default security policy, this is any code installed on the user's local hard drive) has the necessary permissions to access the registry. For more information, see the class. - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read data from the registry|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example reads the value `Name` from `HKEY_CURRENT_USER\Software\MyApp` and displays it in a message box. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet8"::: - + enumeration. Any code running with full trust (under the default security policy, this is any code installed on the user's local hard drive) has the necessary permissions to access the registry. For more information, see the class. + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read data from the registry|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example reads the value `Name` from `HKEY_CURRENT_USER\Software\MyApp` and displays it in a message box. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet8"::: + ]]> @@ -95,45 +95,45 @@ Microsoft.Win32.RegistryKey - Returns a type which provides access to . + Returns a type that provides access to . - class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant only those privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Description| -|-----------|-----------------| -|AllAccess|Create, read, and write access to registry variables.| -|Create|Create access to registry variables.| -|NoAccess|No access to registry variables.| -|Read|Read access to registry variables.| -|Write|Write access to registry variables.| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example gets the names of the subkeys for the `ClassesRoot` registry key and adds them to `ListBox1`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet10"::: - - This example requires that you have a `ListBox` named `ListBox1` in your project. - + class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant only those privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Description| +|-----------|-----------------| +|AllAccess|Create, read, and write access to registry variables.| +|Create|Create access to registry variables.| +|NoAccess|No access to registry variables.| +|Read|Read access to registry variables.| +|Write|Write access to registry variables.| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example gets the names of the subkeys for the `ClassesRoot` registry key and adds them to `ListBox1`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet10"::: + + This example requires that you have a `ListBox` named `ListBox1` in your project. + ]]> @@ -175,43 +175,43 @@ Microsoft.Win32.RegistryKey - Returns a type which provides access to . + Returns a type that provides access to . - class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant only those privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Description| -|-----------|-----------------| -|AllAccess|Create, read, and write access to registry variables.| -|Create|Create access to registry variables.| -|NoAccess|No access to registry variables.| -|Read|Read access to registry variables.| -|Write|Write access to registry variables.| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example creates the subkey `MyDeviceSettings`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet5"::: - + class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant only those privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Description| +|-----------|-----------------| +|AllAccess|Create, read, and write access to registry variables.| +|Create|Create access to registry variables.| +|NoAccess|No access to registry variables.| +|Read|Read access to registry variables.| +|Write|Write access to registry variables.| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example creates the subkey `MyDeviceSettings`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet5"::: + ]]> @@ -253,43 +253,43 @@ Microsoft.Win32.RegistryKey - Returns a type which provides access to . + Returns a type that provides access to . - class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Description| -|-----------|-----------------| -|AllAccess|Create, read, and write access to registry variables.| -|Create|Create access to registry variables.| -|NoAccess|No access to registry variables.| -|Read|Read access to registry variables.| -|Write|Write access to registry variables.| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example deletes the subkey `Software\MyCompany\Preferences\UserData`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet2"::: - + class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Description| +|-----------|-----------------| +|AllAccess|Create, read, and write access to registry variables.| +|Create|Create access to registry variables.| +|NoAccess|No access to registry variables.| +|Read|Read access to registry variables.| +|Write|Write access to registry variables.| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example deletes the subkey `Software\MyCompany\Preferences\UserData`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet2"::: + ]]> @@ -374,26 +374,26 @@ Gets a value from a registry key. Gets a value from a registry key. - The user does not have the permissions required to read from the registry key. @@ -442,38 +442,38 @@ - class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Description| -|-----------|-----------------| -|AllAccess|Create, read, and write access to registry variables.| -|Create|Create access to registry variables.| -|NoAccess|No access to registry variables.| -|Read|Read access to registry variables.| -|Write|Write access to registry variables.| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example opens the subkey `Software\MyCompany\Preferences` and sets the value `FontColor` to `"red"`. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet3"::: - + class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Description| +|-----------|-----------------| +|AllAccess|Create, read, and write access to registry variables.| +|Create|Create access to registry variables.| +|NoAccess|No access to registry variables.| +|Read|Read access to registry variables.| +|Write|Write access to registry variables.| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example opens the subkey `Software\MyCompany\Preferences` and sets the value `FontColor` to `"red"`. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet3"::: + ]]> @@ -520,40 +520,40 @@ - . - - The class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Description| -|-----------|-----------------| -|AllAccess|Create, read, and write access to registry variables.| -|Create|Create access to registry variables.| -|NoAccess|No access to registry variables.| -|Read|Read access to registry variables.| -|Write|Write access to registry variables.| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|To|See| -|--------|---------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example gets the value `ThisSoftware` from the `MyCompany` subkey. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet7"::: - + + This key cannot normally be written to; attempting to create a subkey on it will throw an . + + The class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Description| +|-----------|-----------------| +|AllAccess|Create, read, and write access to registry variables.| +|Create|Create access to registry variables.| +|NoAccess|No access to registry variables.| +|Read|Read access to registry variables.| +|Write|Write access to registry variables.| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|To|See| +|--------|---------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example gets the value `ThisSoftware` from the `MyCompany` subkey. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet7"::: + ]]> @@ -611,33 +611,33 @@ . Value to be written. Required. Writes a value to a registry key. - is . - does not begin with a valid registry root. - - -or- - + does not begin with a valid registry root. + + -or- + is longer than the maximum length allowed (255 characters). The is read-only and thus cannot be written to; for example, it is a root-level node, or it has not been opened with write access. The user does not have the permissions required to create or modify registry keys. @@ -690,37 +690,37 @@ . Required. Writes a value to a registry key. - is . - does not begin with a valid registry root. - - -or- - - is longer than the maximum length allowed (255 characters). - - -or- - + does not begin with a valid registry root. + + -or- + + is longer than the maximum length allowed (255 characters). + + -or- + The type of does not match the registry data type specified by , therefore the data cannot be converted properly. The is read-only, and thus cannot be written to; for example, it is a root-level node, or it has not been opened with write access. The user does not have the permissions required to create or modify registry keys. @@ -768,38 +768,38 @@ - class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. - - Registry permission access values are defined by the enumeration. The following table details its members. - -|Value|Access to Registry Variables| -|-----------|----------------------------------| -|AllAccess|Create, read, and write| -|Create|Create| -|NoAccess|No access.| -|Read|Read| -|Write|Write| - - The following table lists examples of tasks involving the `My.Computer.Registry` object. - -|**To**|**See**| -|------------|-------------| -|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| -|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| -|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| - - - -## Examples - This example counts and displays the number of values in the registry key. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet4"::: - + class, which is in the namespace, controls access to registry variables. Registry variables should not be stored in memory locations where code without can access them. Similarly, when granting permissions, grant the fewest privileges necessary to get the job done. + + Registry permission access values are defined by the enumeration. The following table details its members. + +|Value|Access to Registry Variables| +|-----------|----------------------------------| +|AllAccess|Create, read, and write| +|Create|Create| +|NoAccess|No access.| +|Read|Read| +|Write|Write| + + The following table lists examples of tasks involving the `My.Computer.Registry` object. + +|**To**|**See**| +|------------|-------------| +|Create a registry key and set its value|[How to: Create a Registry Key and Set Its Value](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value)| +|Delete a registry key|[How to: Delete a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key)| +|Read a value from a registry key|[How to: Read a Value from a Registry Key](/dotnet/visual-basic/developing-apps/programming/computer-resources/how-to-read-a-value-from-a-registry-key)| + + + +## Examples + This example counts and displays the number of values in the registry key. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyRegistry/VB/Class1.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Activities.Hosting/WorkflowInstance.xml b/xml/System.Activities.Hosting/WorkflowInstance.xml index 46fef8c8235..850e3376db3 100644 --- a/xml/System.Activities.Hosting/WorkflowInstance.xml +++ b/xml/System.Activities.Hosting/WorkflowInstance.xml @@ -18,27 +18,27 @@ is a lightweight, per-instance runtime for executing a workflow program. It can be constructed to create a new workflow instance or from existing instance state. The APIs that exposes are the minimal set of runtime controls from which higher level operations can be implemented. This API set represents the entire breadth of functionality of the runtime. is an abstract class and relies on a host's implementation of its abstract methods in order to provide host functionality such as synchronization, persistence, tracking, and extensions. - is single threaded and assumes that the host synchronizes all access to it. An attempt to call multiple APIs simultaneously will result in an being thrown. - - Internally, a has two states: Running and Paused. The only way to cause the runtime to transition from paused to running is to call . All actions (except Pause) can only be taken while the runtime is Paused. The runtime will become spontaneously Paused in the following situations: - -- An error fatal to the runtime has occurred. The host will be signaled through (which does not signal a transition to Paused) and then notified through . - -- An exception in the workflow was uncaught and escaped the root. The host will be notified through the method. - -- The scheduler has run out of work items and is now . The host will be notified through the method. Note that the scheduler could have run out of work items because the instance is idle or because the instance is complete. The value of the property can be used to differentiate between the two. - - The host can request a change from Running to Paused by calling the or methods of the instance returned by the property. This request should not be considered to have a specific response meaning that the host should not attempt to correlate an OnNotify* or with a specific call to pause. In response to a pause request, the runtime may transition to Paused and call while the scheduler still has pending work items. The value of the property can be used to determine whether the scheduler has no more work or was interrupted by a request to pause. - - The method of the instance returned by the property is the only method which can be called while the is in the Running state. All other methods will throw an if called.Given the rules for how transitions from one state to another, the public notion of Running and Paused can be defined as follows: - -- Running - The state between a call to and the next WorkflowInstance.OnNotify*. - -- Paused - The state between the last WorkflowInstance.OnNotify* and the next call to . - + is single threaded and assumes that the host synchronizes all access to it. An attempt to call multiple APIs simultaneously will result in an being thrown. + + Internally, a has two states: Running and Paused. The only way to cause the runtime to transition from paused to running is to call . All actions (except Pause) can only be taken while the runtime is Paused. The runtime will become spontaneously Paused in the following situations: + +- An error fatal to the runtime has occurred. The host will be signaled through (which does not signal a transition to Paused) and then notified through . + +- An exception in the workflow was uncaught and escaped the root. The host will be notified through the method. + +- The scheduler has run out of work items and is now . The host will be notified through the method. Note that the scheduler could have run out of work items because the instance is idle or because the instance is complete. The value of the property can be used to differentiate between the two. + + The host can request a change from Running to Paused by calling the or methods of the instance returned by the property. This request should not be considered to have a specific response meaning that the host should not attempt to correlate an OnNotify* or with a specific call to pause. In response to a pause request, the runtime may transition to Paused and call while the scheduler still has pending work items. The value of the property can be used to determine whether the scheduler has no more work or was interrupted by a request to pause. + + The method of the instance returned by the property is the only method that can be called while the is in the Running state. All other methods will throw an if called.Given the rules for how transitions from one state to another, the public notion of Running and Paused can be defined as follows: + +- Running - The state between a call to and the next WorkflowInstance.OnNotify*. + +- Paused - The state between the last WorkflowInstance.OnNotify* and the next call to . + ]]> @@ -348,11 +348,11 @@ Gets or sets the root environment for the workflow instance's arguments and variables. The root environment for the workflow instance's arguments and variables. - returns `true`, an is thrown. - + returns `true`, an is thrown. + ]]> @@ -799,11 +799,11 @@ The reason for aborting the workflow instance. Called by the workflow runtime to notify the host that an abort operation has been requested for the workflow instance. - is called, most APIs except will throw an . It is expected that after is called a host will trend toward a state in which it can satisfy the abort. - + is called, most APIs except will throw an . It is expected that after is called a host will trend toward a state in which it can satisfy the abort. + ]]> @@ -830,11 +830,11 @@ The extension manager to register. Called by the host to register the specified extension manager, validate that all required extensions are present, and to initialize the collection of extensions to be used. - use the runtime type of the object as the type key. Extensions providers added through use the decared type T of the Func\ as the type key. Extension providers contributed by activities through the various *ActivityMetadata.AddDefaultExtensionProvider methods are dropped if a host extension exists for the declared type or if there is a broader type provided through AddDefaultExtensionProvider (ex. if Func\ is provided and Func\ is provided, only Func\ will be kept). If an extension does not exist in the collection that is required by an activity (expressed by calling *ActivityMetadata.RequireExtension) a is thrown. - + use the runtime type of the object as the type key. Extensions providers added through use the decared type T of the Func\ as the type key. Extension providers contributed by activities through the various *ActivityMetadata.AddDefaultExtensionProvider methods are dropped if a host extension exists for the declared type or if there is a broader type provided through AddDefaultExtensionProvider (ex. if Func\ is provided and Func\ is provided, only Func\ will be kept). If an extension does not exist in the collection that is required by an activity (expressed by calling *ActivityMetadata.RequireExtension) a is thrown. + ]]> @@ -886,11 +886,11 @@ Gets or sets the used for scheduling the workflow instance. The synchronization context used for scheduling the workflow instance. - returns `true`, an is thrown. - + returns `true`, an is thrown. + ]]> @@ -914,11 +914,11 @@ Throws an if the workflow instance has been initialized, as determined by . - returns `true`, then an is thrown. - + returns `true`, then an is thrown. + ]]> diff --git a/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml b/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml index edc199ba0cc..76f4e9e23d7 100644 --- a/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml +++ b/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml @@ -16,24 +16,24 @@ Container for all dialog-editing logic for objects. - class to show an inline editor that can have an associated dialog box editor. - - The class can hold either a for a dialog box editor or custom logic that is called when the dialog box is invoked. - - Use the in your to invoke your custom class. - - You can provide a which is shown in a host dialog box, or you can override the method, which enables the reuse of existing or system dialog boxes. - - The following list shows the rules for determining whether the or method is used. - - If the property is not a null reference (Nothing in Visual Basic), that is hosted in a host-specific dialog box, which provides host styling. The is not called. - - If the property is a null reference (Nothing in Visual Basic), the virtual method is called and you can override this method to show any dialog box. - - + class to show an inline editor that can have an associated dialog box editor. + + The class can hold either a for a dialog box editor or custom logic that is called when the dialog box is invoked. + + Use the in your to invoke your custom class. + + You can provide a that's shown in a host dialog box, or you can override the method, which enables the reuse of existing or system dialog boxes. + + The following list shows the rules for determining whether the or method is used. + + If the property is not a null reference (Nothing in Visual Basic), that is hosted in a host-specific dialog box, which provides host styling. The is not called. + + If the property is a null reference (Nothing in Visual Basic), the virtual method is called and you can override this method to show any dialog box. + + ]]> @@ -128,11 +128,11 @@ Gets or sets the that is hosted by a host-specific dialog and has its set to a . The object that is hosted by a host-specific dialog. - method is called instead. - + method is called instead. + ]]> @@ -161,11 +161,11 @@ The that can be used as a source for execution of . Called when the is null and a dialog has been invoked by the user. - that is part of the host's visual tree and that, therefore, can be used to execute property editing commands in such a way that they are handled correctly. Overriding this method enables you to implement any custom dialog logic, such as invoking existing system dialogs. - + that is part of the host's visual tree and that, therefore, can be used to execute property editing commands in such a way that they are handled correctly. Overriding this method enables you to implement any custom dialog logic, such as invoking existing system dialogs. + ]]> diff --git a/xml/System.Activities.Presentation/ActivityDesigner.xml b/xml/System.Activities.Presentation/ActivityDesigner.xml index 58eab577cb0..39e46c8d5ac 100644 --- a/xml/System.Activities.Presentation/ActivityDesigner.xml +++ b/xml/System.Activities.Presentation/ActivityDesigner.xml @@ -16,108 +16,108 @@ Provides a base class for all activity designer components. - and properties of the activity). - - The inherits from and primarily adds the default styling, as well as the ability to customize the icon via the property. It should be used whenever you are creating a designer for a type which derives from . When associated with an type, the property will point to the ModelItem hierarchy describing the instance of that type being edited. - - - -## Examples - In the sample code below, a `First2of3` activity is defined first, then the code for the First2of3 designer is shown, and finally it is shown how to use the Designer attribute to associate the activity with the designer is provided. - -``` - -//The First2of3 activity -using System.Activities; -using System.Collections.Generic; -using System.Linq; - -namespace Microsoft.Activities.Documentation.ActivityTypes -{ - - public sealed class First2of3 : NativeActivity - { - public Activity Activity1 { get; set; } - public Activity Activity2 { get; set; } - public Activity Activity3 { get; set; } - - Variable> ExecutingActivities { get; set; } - - public First2of3() - { - ExecutingActivities = new Variable>(); - } - - // If your activity returns a value, derive from CodeActivity - // and return the value from the Execute method. - protected override void Execute(NativeActivityContext context) - { - // Obtain the runtime value of the Text input argument - var l = new List(); - ExecutingActivities.Set(context, l); - l.Add(context.ScheduleActivity(Activity1, onComplete)); - l.Add(context.ScheduleActivity(Activity2, onComplete)); - l.Add(context.ScheduleActivity(Activity3, onComplete)); - } - - protected override void CacheMetadata(NativeActivityMetadata metadata) - { - metadata.AddImplementationVariable(ExecutingActivities); - metadata.AddChild(Activity1); - metadata.AddChild(Activity2); - metadata.AddChild(Activity3); - } - - private void onComplete(NativeActivityContext context, ActivityInstance completedInstance) - { - var l = ExecutingActivities.Get(context); - l.Remove(completedInstance); - if (l.Count == 1) - { - context.CancelChild(l.Single()); - } - } - } -} - -// Code for the First2of3 Designer: - - - - - - - - - - - - - - - - - - - -//Code for associating the activity with the designer using the Designer attribute. -[Designer(typeof(First2of3Designer))] -public sealed class First2of3 : NativeActivity - -``` - + and properties of the activity). + + The inherits from and primarily adds the default styling, as well as the ability to customize the icon via the property. It should be used whenever you are creating a designer for a type that derives from . When associated with an type, the property will point to the ModelItem hierarchy describing the instance of that type being edited. + + + +## Examples + In the sample code below, a `First2of3` activity is defined first, then the code for the First2of3 designer is shown, and finally it is shown how to use the Designer attribute to associate the activity with the designer is provided. + +``` + +//The First2of3 activity +using System.Activities; +using System.Collections.Generic; +using System.Linq; + +namespace Microsoft.Activities.Documentation.ActivityTypes +{ + + public sealed class First2of3 : NativeActivity + { + public Activity Activity1 { get; set; } + public Activity Activity2 { get; set; } + public Activity Activity3 { get; set; } + + Variable> ExecutingActivities { get; set; } + + public First2of3() + { + ExecutingActivities = new Variable>(); + } + + // If your activity returns a value, derive from CodeActivity + // and return the value from the Execute method. + protected override void Execute(NativeActivityContext context) + { + // Obtain the runtime value of the Text input argument + var l = new List(); + ExecutingActivities.Set(context, l); + l.Add(context.ScheduleActivity(Activity1, onComplete)); + l.Add(context.ScheduleActivity(Activity2, onComplete)); + l.Add(context.ScheduleActivity(Activity3, onComplete)); + } + + protected override void CacheMetadata(NativeActivityMetadata metadata) + { + metadata.AddImplementationVariable(ExecutingActivities); + metadata.AddChild(Activity1); + metadata.AddChild(Activity2); + metadata.AddChild(Activity3); + } + + private void onComplete(NativeActivityContext context, ActivityInstance completedInstance) + { + var l = ExecutingActivities.Get(context); + l.Remove(completedInstance); + if (l.Count == 1) + { + context.CancelChild(l.Single()); + } + } + } +} + +// Code for the First2of3 Designer: + + + + + + + + + + + + + + + + + + + +//Code for associating the activity with the designer using the Designer attribute. +[Designer(typeof(First2of3Designer))] +public sealed class First2of3 : NativeActivity + +``` + ]]> diff --git a/xml/System.Activities.Presentation/ContextItem.xml b/xml/System.Activities.Presentation/ContextItem.xml index e57564fbefa..69a84b159fe 100644 --- a/xml/System.Activities.Presentation/ContextItem.xml +++ b/xml/System.Activities.Presentation/ContextItem.xml @@ -16,11 +16,11 @@ Represents a base class from which all context items must derive. This class is abstract. - , which is part of the employed by a when representing the workflow model visually. The is returned by the property which contains the data that is shared between a host and the designer. This data provides the mechanism needed to hook into subscription and change notification. - + , which is part of the employed by a when representing the workflow model visually. The is returned by the property which contains the data that is shared between a host and the designer. This data provides the mechanism needed to hook into subscription and change notification. + ]]> @@ -67,11 +67,11 @@ When implemented in a derived class, gets the type of item derived from the editing context class. The item . - class. - + class. + ]]> @@ -100,11 +100,11 @@ The previously active . Represents a method that is called on the context item before it is stored in the context item manager. The previous item in the context item manager is passed as a parameter. - diff --git a/xml/System.Activities.Presentation/ObjectReferenceService.xml b/xml/System.Activities.Presentation/ObjectReferenceService.xml index ff34b4dcf0d..a06c980bb90 100644 --- a/xml/System.Activities.Presentation/ObjectReferenceService.xml +++ b/xml/System.Activities.Presentation/ObjectReferenceService.xml @@ -67,7 +67,7 @@ - The object which we need to acquire a reference for. + The object to acquire a reference for. Acquires a reference of an object by its actual reference. A reference of an object. To be added. diff --git a/xml/System.Activities.Statements/State.xml b/xml/System.Activities.Statements/State.xml index 1451a85d9c3..8bb02bce43c 100644 --- a/xml/System.Activities.Statements/State.xml +++ b/xml/System.Activities.Statements/State.xml @@ -14,7 +14,7 @@ - Models the state which a state machine can be in. + Models the state that a state machine can be in. To be added. diff --git a/xml/System.Activities/WorkflowInvoker.xml b/xml/System.Activities/WorkflowInvoker.xml index 1c10aabdf56..fe42f81ac6a 100644 --- a/xml/System.Activities/WorkflowInvoker.xml +++ b/xml/System.Activities/WorkflowInvoker.xml @@ -16,22 +16,22 @@ Provides a means for invoking a workflow as if it were a method call. - contains both instance and static methods for invoking workflows synchronously, and instance methods for invoking workflows asynchronously. - - does not allow instance control such as persisting, unloading, or resuming bookmarks. If instance control is desired, use instead. - - To execute workflows synchronously with no instance control, call the method. To execute a workflow asynchronously with no instance control, use the and method pairs, or the method. - - - -## Examples - The following example synchronously invokes a workflow consisting of a single activity using . - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet1"::: - + contains both instance and static methods for invoking workflows synchronously, and instance methods for invoking workflows asynchronously. + + does not allow instance control such as persisting, unloading, or resuming bookmarks. If instance control is desired, use instead. + + To execute workflows synchronously with no instance control, call the method. To execute a workflow asynchronously with no instance control, use the and method pairs, or the method. + + + +## Examples + The following example synchronously invokes a workflow consisting of a single activity using . + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet1"::: + ]]> @@ -55,18 +55,18 @@ The workflow definition of the workflow to be invoked by this instance of the class. Initializes a new instance of the class. - contains both instance and static methods for invoking workflows synchronously, and instance methods for invoking workflows asynchronously. - - - -## Examples - The following example invokes a workflow consisting of a single activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet2"::: - + contains both instance and static methods for invoking workflows synchronously, and instance methods for invoking workflows asynchronously. + + + +## Examples + The following example invokes a workflow consisting of a single activity. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet2"::: + ]]> @@ -79,11 +79,11 @@ Invokes a workflow asynchronously using the asynchronous design pattern. - @@ -113,22 +113,22 @@ Invokes a workflow asynchronously using the specified and user-provided state. A reference to the asynchronous invoke operation. - from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: - + from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: + ]]> @@ -160,22 +160,22 @@ Invokes a workflow asynchronously using the specified of input parameters, , and user-provided state. A reference to the asynchronous invoke operation. - from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: - + from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: + ]]> @@ -207,25 +207,25 @@ Invokes a workflow asynchronously using the specified time-out interval, , and user-provided state. A reference to the asynchronous invoke operation. - from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown when the method is called. - + from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown when the method is called. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: + ]]> @@ -259,25 +259,25 @@ Invokes a workflow asynchronously using the specified of input parameters, time-out interval, , and user-provided state. A reference to the asynchronous invoke operation. - from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown when is called. - + from the `callback` method. If is called before the workflow completes, it blocks until the workflow completes. If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown when is called. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + This method invokes a workflow asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: + ]]> @@ -304,22 +304,22 @@ The token for the workflow to cancel. Attempts to cancel the workflow that was invoked with the specified . - overloads that takes a `userState` parameter can be canceled. - - If the cancellation succeeds, the property of the passed to the handler is set to `true`; otherwise, it is set to `false`. - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. Once the workflow is invoked, the host attempts to cancel the workflow. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet34"::: - + overloads that takes a `userState` parameter can be canceled. + + If the cancellation succeeds, the property of the passed to the handler is set to `true`; otherwise, it is set to `false`. + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. Once the workflow is invoked, the host attempts to cancel the workflow. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet34"::: + ]]> @@ -347,22 +347,22 @@ Returns the results of a workflow that was invoked using one of the overloads. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - from the `callback` method specified by . If is called before the workflow completes, it blocks until the workflow completes. - - This method returns the result of a workflow invoked asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: - + from the `callback` method specified by . If is called before the workflow completes, it blocks until the workflow completes. + + This method returns the result of a workflow invoked asynchronously using the asynchronous design pattern. For more information, see [Asynchronous Programming Overview](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. These are retrieved by calling . When the call to returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet32"::: + ]]> @@ -386,18 +386,18 @@ Gets the of extensions that are available to workflows invoked by a instance. The of extensions that are available to workflows invoked by a instance. - instance so they will be available to workflows invoked by it. - - - -## Examples - The following example registers a custom with the collection of a instance. This code example is part of the [Custom Tracking](/dotnet/framework/windows-workflow-foundation/samples/custom-tracking) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet40"::: - + instance so they will be available to workflows invoked by it. + + + +## Examples + The following example registers a custom with the collection of a instance. This code example is part of the [Custom Tracking](/dotnet/framework/windows-workflow-foundation/samples/custom-tracking) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet40"::: + ]]> @@ -410,11 +410,11 @@ Invokes a workflow synchronously and returns a dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - overloads that take a . - + overloads that take a . + ]]> @@ -439,24 +439,24 @@ Invokes a workflow synchronously using the workflow definition passed to the constructor. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - overloads that take a . - - - -## Examples - The following example invokes a workflow consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the call to `Invoke` returns, each output argument is returned in the outputs dictionary, keyed by argument name. The workflow is invoked twice, using the workflow definition passed into the `WorkflowInvoker` constructor. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet130"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet31"::: - - If the workflow's root activity has no output arguments or they are not needed by the host, they can be disregarded. The following example invokes a workflow consisting of a single activity that does not have any output arguments. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet2"::: - + overloads that take a . + + + +## Examples + The following example invokes a workflow consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the call to `Invoke` returns, each output argument is returned in the outputs dictionary, keyed by argument name. The workflow is invoked twice, using the workflow definition passed into the `WorkflowInvoker` constructor. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet130"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet31"::: + + If the workflow's root activity has no output arguments or they are not needed by the host, they can be disregarded. The following example invokes a workflow consisting of a single activity that does not have any output arguments. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet2"::: + ]]> @@ -484,24 +484,24 @@ Invokes a workflow synchronously using the specified workflow definition. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - overloads that take a . - - - -## Examples - The following example invokes a workflow consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the call to `Invoke` returns, each output argument is returned in the outputs dictionary, keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet130"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet30"::: - - If the workflow's root activity has no output arguments or they are not needed by the host, they can be disregarded. The following example invokes a workflow consisting of a single activity that does not have any output arguments. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet1"::: - + overloads that take a . + + + +## Examples + The following example invokes a workflow consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the call to `Invoke` returns, each output argument is returned in the outputs dictionary, keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet130"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet30"::: + + If the workflow's root activity has no output arguments or they are not needed by the host, they can be disregarded. The following example invokes a workflow consisting of a single activity that does not have any output arguments. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet1"::: + ]]> @@ -529,26 +529,26 @@ Invokes the activity passed to the constructor synchronously with the specified of input parameters. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - overloads that take a . - - - -## Examples - The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet120"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet22"::: - - If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke`, such as this one, must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into the `WorkflowInvoker` constructor must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that this overload of `Invoke`, which returns a dictionary of arguments instead of a single return value, is used. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet121"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet23"::: - + overloads that take a . + + + +## Examples + The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet120"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet22"::: + + If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke`, such as this one, must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into the `WorkflowInvoker` constructor must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that this overload of `Invoke`, which returns a dictionary of arguments instead of a single return value, is used. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet121"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet23"::: + ]]> @@ -576,28 +576,28 @@ Invokes a workflow synchronously with the specified time-out interval. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - is thrown. - + is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - - -## Examples - The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown and the following message is displayed. - -```Output -The operation did not complete within the allotted timeout of 00:00:30. -The time allotted to this operation may have been a portion of a longer timeout. -``` - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet51"::: - - For an example of using `Invoke` with output arguments, see the overload of with the same parameters as this overload without the time-out interval. - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + + +## Examples + The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown and the following message is displayed. + +```Output +The operation did not complete within the allotted timeout of 00:00:30. +The time allotted to this operation may have been a portion of a longer timeout. +``` + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet51"::: + + For an example of using `Invoke` with output arguments, see the overload of with the same parameters as this overload without the time-out interval. + ]]> @@ -627,26 +627,26 @@ The time allotted to this operation may have been a portion of a longer timeout. Invokes a workflow synchronously using the specified workflow definition and of input parameters. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - overloads that take a . - - - -## Examples - The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet120"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet20"::: - - If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke`, such as this one, must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into `Invoke` must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that this overload of `Invoke`, which returns a dictionary of arguments instead of a single return value, is used. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet121"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet21"::: - + overloads that take a . + + + +## Examples + The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet120"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet20"::: + + If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke`, such as this one, must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into `Invoke` must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that this overload of `Invoke`, which returns a dictionary of arguments instead of a single return value, is used. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet121"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet21"::: + ]]> @@ -682,23 +682,23 @@ The time allotted to this operation may have been a portion of a longer timeout. Invokes a workflow synchronously using the specified workflow definition and time-out interval. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - is thrown. - + is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - - -## Examples - The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet50"::: - - For an example of using `Invoke` with output arguments, see the overload of with the same parameters as this overload without the time-out interval. - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + + +## Examples + The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet50"::: + + For an example of using `Invoke` with output arguments, see the overload of with the same parameters as this overload without the time-out interval. + ]]> @@ -728,28 +728,28 @@ The time allotted to this operation may have been a portion of a longer timeout. Invokes the activity passed to the constructor synchronously with the specified of input parameters and the specified time-out interval. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - is thrown. - + is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - - -## Examples - The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown and the following message is displayed. - -```Output -The operation did not complete within the allotted timeout of 00:00:30. -The time allotted to this operation may have been a portion of a longer timeout. -``` - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet51"::: - - For an example of using `Invoke` with input and output arguments, see the overload of with the same parameters as this overload without the time-out interval. - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + + +## Examples + The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown and the following message is displayed. + +```Output +The operation did not complete within the allotted timeout of 00:00:30. +The time allotted to this operation may have been a portion of a longer timeout. +``` + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet51"::: + + For an example of using `Invoke` with input and output arguments, see the overload of with the same parameters as this overload without the time-out interval. + ]]> @@ -787,23 +787,23 @@ The time allotted to this operation may have been a portion of a longer timeout. Invokes a workflow synchronously using the specified workflow definition, of input parameters, and time-out interval. A dictionary of the root activity's and values keyed by argument name that represent the outputs of the workflow. - is thrown. - + is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - - -## Examples - The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet50"::: - - For an example of using `Invoke` with input and output arguments, see the overload of with the same parameters as this overload without the time-out interval. - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + + +## Examples + The following example invokes a workflow that contains two activities and a activity configured with a of one minute. This workflow is invoked twice; the first time with a time-out interval of two minutes, and the second time with a time-out interval of 30 seconds. The first workflow completes successfully, but the second one does not and a is thrown. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet50"::: + + For an example of using `Invoke` with input and output arguments, see the overload of with the same parameters as this overload without the time-out interval. + ]]> @@ -841,19 +841,19 @@ The time allotted to this operation may have been a portion of a longer timeout. Invokes a workflow synchronously using the workflow definition passed to the constructor. A value of type TResult with the result of the execution of the activity. - overloads that take a . ## Examples -The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: - +The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: + ]]> @@ -887,22 +887,22 @@ The following example invokes a workflow consisting of a single `Add` activity t Invokes a workflow synchronously using the specified workflow definition and of input parameters. A value of type TResult with the result of the execution of the activity. - overloads that take a . - + overloads that take a . + > [!NOTE] > The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete, completes successfully if the workflow does not become idle. ## Examples -The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: - +The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: + ]]> @@ -938,22 +938,22 @@ The following example invokes a workflow consisting of a single `Add` activity t Invokes a workflow synchronously using the specified workflow definition, of input parameters, and time-out interval. A value of type TResult with the result of the execution of the activity. - is thrown. - + is thrown. + > [!NOTE] > The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete, completes successfully if the workflow does not become idle. ## Examples -The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: - +The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: + ]]> @@ -991,22 +991,22 @@ The following example invokes a workflow consisting of a single `Add` activity t Invokes a workflow synchronously using the specified workflow definition, of input parameters, of additional output parameters, and time-out interval. A value of type TResult with the result of the execution of the activity. - is thrown. - + is thrown. + > [!NOTE] > The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete, completes successfully if the workflow does not become idle. ## Examples -The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: - +The following example invokes a workflow consisting of a single `Add` activity that has two input arguments and since it derives from `CodeActivity` it has one well-defined output argument. When the workflow is invoked, the `arguments` dictionary is passed that contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, the value of the output argument is returned. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet110"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet10"::: + ]]> @@ -1019,13 +1019,13 @@ The following example invokes a workflow consisting of a single `Add` activity t Invokes a workflow asynchronously using the event-based asynchronous design pattern. - . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - + . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + ]]> @@ -1049,20 +1049,20 @@ The following example invokes a workflow consisting of a single `Add` activity t Invokes a workflow asynchronously. - . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - + . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: ]]> @@ -1097,20 +1097,20 @@ The following example invokes a workflow consisting of a single `Add` activity t The dictionary of input parameters to the workflow, keyed by argument name. Invokes a workflow asynchronously using the specified of input parameters. - . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - + . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: ]]> @@ -1139,24 +1139,24 @@ The following example invokes a workflow consisting of a single `Add` activity t A user-provided object used to distinguish this particular asynchronous invoke operation from other current asynchronous invoke operations. Invokes a workflow asynchronously using the specified unique identifier. - operations for the current activity. If the `userState` parameter is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . - - To be notified when the workflow is complete, handle . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: - + operations for the current activity. If the `userState` parameter is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . + + To be notified when the workflow is complete, handle . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: + ]]> @@ -1189,23 +1189,23 @@ The following example invokes a workflow consisting of a single `Add` activity t The interval in which the workflow must complete before it is aborted and a is thrown. Invokes a workflow asynchronously with the specified time-out interval. - . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. - + . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: ]]> @@ -1236,24 +1236,24 @@ The following example invokes a workflow consisting of a single `Add` activity t A user-provided object used to distinguish this particular asynchronous invoke operation from other current asynchronous invoke operations. Invokes a workflow asynchronously using the specified of input parameters and a unique identifier. - operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . - - To be notified when the workflow is complete, handle . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: - + operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . + + To be notified when the workflow is complete, handle . To configure a time-out interval in which the workflow must complete, use one of the overloads that take a . + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: + ]]> @@ -1288,23 +1288,23 @@ The following example invokes a workflow consisting of a single `Add` activity t The interval in which the workflow must complete before it is aborted and a is thrown. Invokes a workflow asynchronously with the specified of input parameters and the specified time-out interval. - . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. - + . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: ]]> @@ -1335,27 +1335,27 @@ This method stores in the task it returns all non-usage exceptions that the meth A user-provided object used to distinguish this particular asynchronous invoke operation from other current asynchronous invoke operations. Invokes a workflow asynchronously with the specified time-out interval and a unique identifier. - operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . - - To be notified when the workflow is complete, handle . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. - + operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . + + To be notified when the workflow is complete, handle . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: + ]]> @@ -1386,27 +1386,27 @@ This method stores in the task it returns all non-usage exceptions that the meth A user-provided object used to distinguish this particular asynchronous invoke operation from other current asynchronous invoke operations. Invokes a workflow asynchronously with the specified of input parameters, the specified time-out interval, and a unique identifier. - operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . - - To be notified when the workflow is complete, handle . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. - + operations for the current activity. If `userState` is not unique, an is thrown. `userState` is used to identify the workflow in , and to cancel the workflow using . + + To be notified when the workflow is complete, handle . If the workflow does not complete within the specified time-out interval the workflow is aborted and a is thrown. + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + This method invokes a workflow asynchronously using the event-based asynchronous design pattern. For more information, see [Event-based Asynchronous Pattern Overview](/dotnet/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview). + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: + ]]> @@ -1430,20 +1430,20 @@ This method stores in the task it returns all non-usage exceptions that the meth Occurs when the workflow invoked by one of the overloads is completed or canceled. - overloads completed successfully and to retrieve the output arguments of the completed workflow. - - - -## Examples - The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: - + overloads completed successfully and to retrieve the output arguments of the completed workflow. + + + +## Examples + The following example invokes a workflow consisting of a `LongRunningDiceRoll` activity. The `LongRunningDiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes these are retrieved in the handler. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet131"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs" id="Snippet33"::: + ]]> 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.CodeDom.Compiler/CodeGenerator.xml b/xml/System.CodeDom.Compiler/CodeGenerator.xml index 291fc1d0f51..e99d71cddf0 100644 --- a/xml/System.CodeDom.Compiler/CodeGenerator.xml +++ b/xml/System.CodeDom.Compiler/CodeGenerator.xml @@ -37,14 +37,14 @@ Provides an example implementation of the interface. This class is abstract. - [!NOTE] -> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). - +> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). + ]]> @@ -163,14 +163,14 @@ Creates an escaped identifier for the specified value. The escaped identifier for the value. - tests whether the identifier conflicts with reserved or language keywords, and if so, returns an equivalent name with language-specific escape code formatting. The returned name is referred to an escaped identifier. The escaped identifier contains the same `value` but includes escape code formatting to differentiate it from conflicting keywords. For example, `value` could be preceded by an at sign ("@") or delimited by square brackets ("[" and "]") to create an escaped identifier. - + tests whether the identifier conflicts with reserved or language keywords, and if so, returns an equivalent name with language-specific escape code formatting. The returned name is referred to an escaped identifier. The escaped identifier contains the same `value` but includes escape code formatting to differentiate it from conflicting keywords. For example, `value` could be preceded by an at sign ("@") or delimited by square brackets ("[" and "]") to create an escaped identifier. + > [!NOTE] -> The default implementation of this method does nothing. - +> The default implementation of this method does nothing. + ]]> @@ -212,14 +212,14 @@ Creates a valid identifier for the specified value. A valid identifier for the value. - tests whether the identifier conflicts with reserved or language keywords, and if so, returns a valid identifier name that does not conflict. The returned identifier contains the same `value` but includes escape code formatting to differentiate it from conflicting keywords. Typically, if the value requires modification, it is preceded by an underscore "_". - + tests whether the identifier conflicts with reserved or language keywords, and if so, returns a valid identifier name that does not conflict. The returned identifier contains the same `value` but includes escape code formatting to differentiate it from conflicting keywords. Typically, if the value requires modification, it is preceded by an underscore "_". + > [!NOTE] -> The default implementation of this method does nothing. - +> The default implementation of this method does nothing. + ]]> @@ -794,11 +794,11 @@ The options to use when generating the code. Generates code for the specified class member using the specified text writer and code generator options. - The property is not . @@ -1071,11 +1071,11 @@ The statement to generate code for. Generates code for the specified conditional statement. - @@ -1769,11 +1769,11 @@ The statement to generate code for. Generates code for the specified iteration statement. - @@ -2388,26 +2388,26 @@ Generates code for the specified primitive expression. To be added. - uses an invalid data type. Only the following data types are valid: - -- string - -- char - -- byte - -- Int16 - -- Int32 - -- Int64 + uses an invalid data type. Only the following data types are valid: + +- string + +- char + +- byte + +- Int16 + +- Int32 + +- Int64 - Half - -- Single - -- Double - + +- Single + +- Double + - Decimal @@ -3331,11 +3331,11 @@ Gets or sets the amount of spaces to indent each indentation level. The number of spaces to indent for each indentation level. - @@ -3597,11 +3597,11 @@ if the specified string is a valid identifier; otherwise, . - method calls this method to perform string validation. Calling the method and passing a before generating code from it can prevent the use of certain character sequences to include hidden code within an identifier field. - + method calls this method to perform string validation. Calling the method and passing a before generating code from it can prevent the use of certain character sequences to include hidden code within an identifier field. + ]]> @@ -4313,11 +4313,11 @@ Converts the specified string by formatting it with escape codes. The converted string. - @@ -4948,15 +4948,15 @@ An object to test for invalid identifiers. Attempts to validate each identifier field contained in the specified or tree. - objects to contain field escape characters and hidden code which can allow security violations. This method checks the literal fields of each in a tree for characters which could be used to hide code, and throws an exception if an identifier field contains an invalid character. - - This method calls the method to validate each identifier in the specified or tree, and throws an exception if an identifier is invalid or contains invalid characters. - - Call this method and pass it the containing the code graph to generate before generating code to block the use of certain character sequences that can be used to include hidden code within an identifier field. This method is not called automatically by any generate code methods. - + objects to contain field escape characters and hidden code, which can allow security violations. This method checks the literal fields of each in a tree for characters which could be used to hide code, and throws an exception if an identifier field contains an invalid character. + + This method calls the method to validate each identifier in the specified or tree, and throws an exception if an identifier is invalid or contains invalid characters. + + Call this method and pass it the containing the code graph to generate before generating code to block the use of certain character sequences that can be used to include hidden code within an identifier field. This method is not called automatically by any generate code methods. + ]]> The specified contains an invalid identifier. diff --git a/xml/System.CodeDom.Compiler/CompilerError.xml b/xml/System.CodeDom.Compiler/CompilerError.xml index e353109959f..689e6be3d65 100644 --- a/xml/System.CodeDom.Compiler/CompilerError.xml +++ b/xml/System.CodeDom.Compiler/CompilerError.xml @@ -40,23 +40,23 @@ Represents a compiler error or warning. - represents a compiler error or a warning that has been returned by the compiler. - + represents a compiler error or a warning that has been returned by the compiler. + > [!NOTE] -> This class contains an inheritance demand at the class level that applies to all members. A is thrown when the derived class does not have full-trust permission. For details about inheritance demands, see [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). - - - -## Examples - The following example compiles a CodeDOM program graph and provides an example of how to programmatically access CompilerError data. - +> This class contains an inheritance demand at the class level that applies to all members. A is thrown when the derived class does not have full-trust permission. For details about inheritance demands, see [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). + + + +## Examples + The following example compiles a CodeDOM program graph and provides an example of how to programmatically access CompilerError data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic CompilerError Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.CodeDom.Compiler/CompilerError/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic CompilerError Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic CompilerError Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -191,11 +191,11 @@ Gets or sets the column number where the source of the error occurs. The column number of the source file where the compiler encountered the error. - property can be set to zero for compilers that do not return column information. - + property can be set to zero for compilers that do not return column information. + ]]> @@ -242,11 +242,11 @@ Gets or sets the error number. The error number as a string. - property can contain a string of any length. - + property can contain a string of any length. + ]]> @@ -293,11 +293,11 @@ Gets or sets the text of the error message. The text of the error message. - property can be a string of any length. - + property can be a string of any length. + ]]> @@ -341,8 +341,8 @@ System.String - Gets or sets the file name of the source file that contains the code which caused the error. - The file name of the source file that contains the code which caused the error. + Gets or sets the file name of the source file that contains the code that caused the error. + The file name of the source file that contains the code that caused the error. To be added. @@ -468,11 +468,11 @@ Provides an implementation of Object's method. A string representation of the compiler error. - objects can be treated as objects for simplified debugging output. - + objects can be treated as objects for simplified debugging output. + ]]> diff --git a/xml/System.Collections.Specialized/HybridDictionary.xml b/xml/System.Collections.Specialized/HybridDictionary.xml index edf4d65bc99..de9a4c7fcca 100644 --- a/xml/System.Collections.Specialized/HybridDictionary.xml +++ b/xml/System.Collections.Specialized/HybridDictionary.xml @@ -71,7 +71,7 @@ with small collections, and offers the flexibility of switching to a which handles larger collections better than . + This class is recommended for cases where the number of elements in a dictionary is unknown. It takes advantage of the improved performance of a with small collections, and offers the flexibility of switching to a , which handles larger collections better than . If the initial size of the collection is greater than the optimal size for a , the collection is stored in a to avoid the overhead of copying elements from the to a . diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml index f5c7de10428..7fe655f7f92 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml @@ -94,9 +94,7 @@ `null` is allowed as a key or as a value. > [!CAUTION] -> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. - - +> The method does not distinguish between `null` that's returned because the specified key is not found and `null` that's returned because the value associated with the key is `null`. ## Examples The following code example shows how to implement and use the class. diff --git a/xml/System.Collections.Specialized/NameValueCollection.xml b/xml/System.Collections.Specialized/NameValueCollection.xml index 440684fe5e9..17d631a0b99 100644 --- a/xml/System.Collections.Specialized/NameValueCollection.xml +++ b/xml/System.Collections.Specialized/NameValueCollection.xml @@ -76,9 +76,7 @@ `null` is allowed as a key or as a value. > [!CAUTION] -> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. - - +> The method does not distinguish between `null` that's returned because the specified key is not found and `null` that's returned because the value associated with the key is `null`. ## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameValueCollection2/CPP/nvc.cpp" id="Snippet1"::: diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index 33f96f98abd..c30f843970f 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -1911,8 +1911,8 @@ This method is an `O(1)` operation. The zero-based index at which the range starts. The number of elements in the range. - Returns an which represents a subset of the elements in the source . - An which represents a subset of the elements in the source . + Returns an that represents a subset of the elements in the source . + An that represents a subset of the elements in the source . The object to copy to a new object. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the specified load factor, and the default hash code provider and comparer. The approximate number of elements that the object can initially contain. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. Initializes a new, empty instance of the class using the specified initial capacity and load factor, and the default hash code provider and comparer. The object to copy to a new object. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. The object that defines the hash code provider and the comparer to use with the . -or- @@ -1435,7 +1435,7 @@ Each element is a key/value pair stored in a The approximate number of elements that the object can initially contain. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. The object that defines the hash code provider and the comparer to use with the . -or- @@ -1550,7 +1550,7 @@ Each element is a key/value pair stored in a The object to copy to a new object. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. The object that supplies the hash codes for all keys in the . -or- @@ -1660,7 +1660,7 @@ Each element is a key/value pair stored in a The approximate number of elements that the object can initially contain. - A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. + A number in the range from 0.1 through 1.0 that is multiplied by the default value that provides the best performance. The result is the maximum ratio of elements to buckets. The object that supplies the hash codes for all keys in the . -or- 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.Diagnostics.Metrics/MeterListener.xml b/xml/System.Diagnostics.Metrics/MeterListener.xml index d9fc498386e..cdb7a70569d 100644 --- a/xml/System.Diagnostics.Metrics/MeterListener.xml +++ b/xml/System.Diagnostics.Metrics/MeterListener.xml @@ -274,8 +274,8 @@ The type of the numeric measurement. - The callback which can be used to get measurement recording of numeric type T. - Sets a callback for a specific numeric type to get the measurement recording notification from all instruments which enabled listening and was created with the same specified numeric type. + The callback that can be used to get measurement recording of numeric type T. + Sets a callback for a specific numeric type to get the measurement recording notification from all instruments that enabled listening and were created with the same specified numeric type. If a measurement of type T is recorded and a callback of type T is registered, that callback will be used. To be added. diff --git a/xml/System.Diagnostics/ActivityCreationOptions`1.xml b/xml/System.Diagnostics/ActivityCreationOptions`1.xml index 9cb60790f22..3d7bb82b494 100644 --- a/xml/System.Diagnostics/ActivityCreationOptions`1.xml +++ b/xml/System.Diagnostics/ActivityCreationOptions`1.xml @@ -67,7 +67,7 @@ The possible generic type parameters are The name of the event being written. - An object that represents the additional context for IsEnabled. Consumers should expect to receive which may indicate that producer called pure IsEnabled(string) to check if consumer wants to get notifications for such events at all. Based on that, producer may call IsEnabled(string, object, object) again with non- context. - Optional. An object that represents the additional context for IsEnabled. by default. Consumers should expect to receive which may indicate that producer called pure IsEnabled(string) or producer passed all necessary context in . + An object that represents the additional context for IsEnabled. Consumers should expect to receive , which might indicate that producer called pure IsEnabled(string) to check if consumer wants to get notifications for such events at all. Based on that, producer may call IsEnabled(string, object, object) again with non- context. + Optional. An object that represents the additional context for IsEnabled. by default. Consumers should expect to receive , which might indicate that producer called pure IsEnabled(string) or producer passed all necessary context in . Verifies it the notification event is enabled. if the notification event is enabled, otherwise. @@ -546,7 +546,7 @@ Consumers can access The name of the event being written. - An object that represents the value being passed as a payload for the event. This is often an anonymous type which contains several sub-values. + An object that represents the value being passed as a payload for the event. This is often an anonymous type that contains several subvalues. Provides a generic way of logging complex payloads. diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index f747f96ee6c..d8956b56261 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -17,94 +17,94 @@ Directs tracing or debugging output of end-to-end events to an XML-encoded, schema-compliant log file. - class provides tracing of end-to-end schema-compliant events. You can use end-to-end tracing for a system that has heterogeneous components that cross thread, , process, and computer boundaries. A standardized event schema enables tracing across these boundaries. The schema enables the addition of custom, schema-compliant elements. You can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](/dotnet/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe) to display the event data. - - is tuned for logging performance with implicit support for lock-free tracing. - - The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables later in this section. - -You can create an object in your code. Alternatively, for .NET Framework apps, you can enable or disable an object through the application configuration file, and then use the configured object in your application. For information about the use of configuration files for tracing and debugging in .NET Framework apps, see [Trace and Debug Settings Schema](/dotnet/framework/configure-apps/file-schema/trace-debug/). - - To configure an object in a .NET Framework app, modify the configuration file that corresponds to the name of your application. In this file, you can add, remove, or set the properties for a listener. The configuration file should be formatted as follows: - -```xml - - - - - - - - - - - - - -``` - - The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. - - If an attempt is made to write to a file that is being used or is unavailable, a GUID suffix is automatically added to the file name. - + class provides tracing of end-to-end schema-compliant events. You can use end-to-end tracing for a system that has heterogeneous components that cross thread, , process, and computer boundaries. A standardized event schema enables tracing across these boundaries. The schema enables the addition of custom, schema-compliant elements. You can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](/dotnet/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe) to display the event data. + + is tuned for logging performance with implicit support for lock-free tracing. + + The class converts tracing and debugging information into an XML-encoded text stream. The description of the XML output is shown in the tables later in this section. + +You can create an object in your code. Alternatively, for .NET Framework apps, you can enable or disable an object through the application configuration file, and then use the configured object in your application. For information about the use of configuration files for tracing and debugging in .NET Framework apps, see [Trace and Debug Settings Schema](/dotnet/framework/configure-apps/file-schema/trace-debug/). + + To configure an object in a .NET Framework app, modify the configuration file that corresponds to the name of your application. In this file, you can add, remove, or set the properties for a listener. The configuration file should be formatted as follows: + +```xml + + + + + + + + + + + + + +``` + + The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + + If an attempt is made to write to a file that is being used or is unavailable, a GUID suffix is automatically added to the file name. + > [!NOTE] -> Listener methods are intended to be called by methods of the , , and classes. Do not call the listener methods directly from application code. The listener is primarily intended for use by the class. - - The following table describes the elements and attributes of the XML output. - -|Element|Attributes|Output|Notes| -|-------------|----------------|------------|-----------| -|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table.| -|`Computer`|None|Always present.|This element represents the value of the property.| -|`Correlation`|`ActivityID`|Always present.|If `ActivityID` is not specified, the default is an empty GUID.| -||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the `Trace` method call.|The `RelatedActivityID` attribute corresponds to the `relatedActivityId` parameter of the method.| -|`Data`|None|Always present.|This element represents parameter input (`data`). One element is provided for each data object. In the case of event logs, the `Data` element contains escaped XML data. In the case of data logs, the `Data` element contains unescaped data. The data log output uses the `ToString` method of the passed-in data objects.| -|`Event`|None|Always present.|This element contains a trace event.| -|`EventData`|None|Present for event logs.|This element represents parameter input (`message`, `args`). It contains `Data` elements with escaped XML data that is created by calling the method.| -|`EventID`|None|Always present.|This element represents parameter input (`id`).| -|`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the .| -||`ThreadID`|Present when `ProcessID` is present.|The `ThreadID` attribute is specified in the .| -|`Level`|None|Always present.|This element represents parameter input (the numeric value of `eventType`). Parameter values that are larger than 255 are output as a level 8, which represents . Trace event types , , , , and are output as levels 1, 2, 4, 8, and 10, respectively.| -|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|Only one logical operation can exist. Therefore, the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| -|`OpCode`|None|Present when `Level` is greater than 255.|This element represents Trace event types that have numeric values greater than 255. , , , , or are output as levels 1, 2, 4, 8, and 10, respectively.| -|`Provider`|`GUID`|Always present.|Always empty.| -|`RenderingInfo`|`Culture`|Always present.|This attribute represents a resource string for the event type. It is always "en-EN\\".| -|`System`|`Name`|Always present.|| -|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| -|`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| -|`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| - - The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the `UserData` element, which contains user-provided, unescaped data. The `UserData` element is a result of calls to the method. - -|Escaped character|Value| -|-----------------------|-----------| -|&|&| -|\<|<| -|>|>| -|"|"| -|\|'| -|0xD|&\#xD;| +> Listener methods are intended to be called by methods of the , , and classes. Do not call the listener methods directly from application code. The listener is primarily intended for use by the class. + + The following table describes the elements and attributes of the XML output. + +|Element|Attributes|Output|Notes| +|-------------|----------------|------------|-----------| +|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table.| +|`Computer`|None|Always present.|This element represents the value of the property.| +|`Correlation`|`ActivityID`|Always present.|If `ActivityID` is not specified, the default is an empty GUID.| +||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the `Trace` method call.|The `RelatedActivityID` attribute corresponds to the `relatedActivityId` parameter of the method.| +|`Data`|None|Always present.|This element represents parameter input (`data`). One element is provided for each data object. In the case of event logs, the `Data` element contains escaped XML data. In the case of data logs, the `Data` element contains unescaped data. The data log output uses the `ToString` method of the passed-in data objects.| +|`Event`|None|Always present.|This element contains a trace event.| +|`EventData`|None|Present for event logs.|This element represents parameter input (`message`, `args`). It contains `Data` elements with escaped XML data that is created by calling the method.| +|`EventID`|None|Always present.|This element represents parameter input (`id`).| +|`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the .| +||`ThreadID`|Present when `ProcessID` is present.|The `ThreadID` attribute is specified in the .| +|`Level`|None|Always present.|This element represents parameter input (the numeric value of `eventType`). Parameter values that are larger than 255 are output as a level 8, which represents . Trace event types , , , , and are output as levels 1, 2, 4, 8, and 10, respectively.| +|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|Only one logical operation can exist. Therefore, the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| +|`OpCode`|None|Present when `Level` is greater than 255.|This element represents Trace event types that have numeric values greater than 255. , , , , or are output as levels 1, 2, 4, 8, and 10, respectively.| +|`Provider`|`GUID`|Always present.|Always empty.| +|`RenderingInfo`|`Culture`|Always present.|This attribute represents a resource string for the event type. It is always "en-EN\\".| +|`System`|`Name`|Always present.|| +|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| +|`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| +|`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| + + The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the `UserData` element, which contains user-provided, unescaped data. The `UserData` element is a result of calls to the method. + +|Escaped character|Value| +|-----------------------|-----------| +|&|&| +|\<|<| +|>|>| +|"|"| +|\|'| +|0xD|&\#xD;| |0xA|&\#xA;| - -## Examples - The following code example demonstrates how to use the class. - + +## Examples + The following code example demonstrates how to use the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/CPP/eventschematracelistener.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet1"::: + ]]> @@ -138,19 +138,19 @@ You can create an object in y The path for the log file. Initializes a new instance of the class, using the specified file as the recipient of debugging and tracing output. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet1"::: + ]]> @@ -183,14 +183,14 @@ You can create an object in y The name of the listener. Initializes a new instance of the class with the specified name, using the specified file as the recipient of debugging and tracing output. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet2"::: + ]]> @@ -225,19 +225,19 @@ You can create an object in y The size of the output buffer, in bytes. Initializes a new instance of the class with the specified name and specified buffer size, using the specified file as the recipient of debugging and tracing output. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet3"::: + ]]> @@ -268,19 +268,19 @@ You can create an object in y One of the values. Initializes a new instance of the class with the specified name and specified buffer size, using the specified file with the specified log retention policy as the recipient of the debugging and tracing output. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet4"::: + ]]> @@ -319,19 +319,17 @@ You can create an object in y The maximum file size, in bytes. Initializes a new instance of the class with the specified name and specified buffer size, using the specified file with the specified log retention policy and maximum size as the recipient of the debugging and tracing output. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/.ctor/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb" id="Snippet5"::: + ]]> @@ -373,19 +371,19 @@ You can create an object in y The maximum number of output log files. Initializes a new instance of the class with the specified name and specified buffer size, using the specified file with the specified log retention policy, maximum size, and file count as the recipient of the debugging and tracing output. - constructor. This code example is part of a larger example that is provided for the class. - + constructor. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet2"::: + ]]> @@ -425,19 +423,19 @@ You can create an object in y Gets the size of the output buffer. The size of the output buffer, in bytes. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet5"::: + ]]> @@ -540,11 +538,11 @@ You can create an object in y Gets the custom XML configuration attributes that the trace listener supports. A array that contains the XML configuration attributes recognized by this listener. - class. Using any other attribute causes a configuration exception. The method for the returns the following string array values: "bufferSize", "logRetentionOption", "maximumFileSize", and "maximumNumberOfFiles". - + class. Using any other attribute causes a configuration exception. The method for the returns the following string array values: "bufferSize", "logRetentionOption", "maximumFileSize", and "maximumNumberOfFiles". + ]]> @@ -569,14 +567,14 @@ You can create an object in y Gets a value indicating whether the trace listener is thread safe. Always returns . - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet4"::: + ]]> @@ -601,29 +599,29 @@ You can create an object in y Gets the maximum size of the log file. The maximum file size, in bytes. - property value is not an absolute; it is a threshold that can be exceeded up to the size of the last message. - - The following table shows the possible and default values for file size that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. - -|TraceLogRetentionOption|Maximum file size|Default file size| -|-----------------------------|-----------------------|-----------------------| -||N/A|-1| -||>0|4 KB| -||>0|4 KB| -||>0|4 KB| -||>0|4 KB| - - - -## Examples - The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. - + property value is not an absolute; it is a threshold that can be exceeded up to the size of the last message. + + The following table shows the possible and default values for file size that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. + +|TraceLogRetentionOption|Maximum file size|Default file size| +|-----------------------------|-----------------------|-----------------------| +||N/A|-1| +||>0|4 KB| +||>0|4 KB| +||>0|4 KB| +||>0|4 KB| + + + +## Examples + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet6"::: + ]]> @@ -648,29 +646,29 @@ You can create an object in y Gets the maximum number of log files. The maximum number of log files, determined by the value of the property for the file. - property is not checked for that value. - -|TraceLogRetentionOption|Maximum number of files|Default number of files| -|-----------------------------|-----------------------------|-----------------------------| -||N/A|1| -||N/A|1| -||N/A|-1| -||>0|1| -||>1|2| - - - -## Examples - The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. - + property is not checked for that value. + +|TraceLogRetentionOption|Maximum number of files|Default number of files| +|-----------------------------|-----------------------------|-----------------------------| +||N/A|1| +||N/A|1| +||N/A|-1| +||>0|1| +||>1|2| + + + +## Examples + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet7"::: + ]]> @@ -721,14 +719,14 @@ You can create an object in y A data object to emit. Writes trace information, a single data object, and event information to the log file. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -777,14 +775,14 @@ You can create an object in y An array of data objects to emit. Writes trace information, multiple data objects, and event information to the log file. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -835,14 +833,14 @@ You can create an object in y The message to write. Writes trace information, a message, and event information to the log file. - [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -893,14 +891,14 @@ You can create an object in y An object array that contains zero or more objects to format. Writes trace information, a formatted message, and event information to the log file. - method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. - + method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. + > [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -925,14 +923,14 @@ You can create an object in y Gets the trace log retention option for the file. One of the values. The default is . - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener/vb/program.vb" id="Snippet9"::: + ]]> @@ -974,14 +972,14 @@ You can create an object in y A structure that identifies a related activity. Writes trace information, including the identity of a related activity, a message, and event information, to the log file. - method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . - + method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . + > [!IMPORTANT] -> The method should not be called by application code. It is intended to be used by a object to emit the trace information for its method. - +> The method should not be called by application code. It is intended to be used by a object to emit the trace information for its method. + ]]> @@ -1009,14 +1007,14 @@ You can create an object in y The message to write. Writes a message to the log file without providing any additional context information. - method is called to log the message as an event. - + method is called to log the message as an event. + > [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -1044,14 +1042,14 @@ You can create an object in y The message to write. Writes a message followed by the current line terminator to the log file without providing any additional context information. - method is called to log the message as an event. - + method is called to log the message as an event. + > [!IMPORTANT] -> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. - +> This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -1082,11 +1080,11 @@ You can create an object in y Gets or sets the underlying text writer that writes to the log file. A object. - property raises a . - + property raises a . + ]]> An attempt was made to assign a value to the property. diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index b89a7cacc09..b1cd1f97feb 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -2069,7 +2069,7 @@ There are problems accessing the performance counter APIs used to get process in ## Remarks An application can obtain a handle to a process that can be used as a parameter to many process-information and control functions. You can use this handle to initialize a or to call native methods with platform invoke. - This process handle is private to an application--in other words, process handles cannot be shared. A process also has a process which, unlike the , is unique and, therefore, valid throughout the system. + This process handle is private to an application. In other words, process handles cannot be shared. A process also has a process that, unlike the , is unique and, therefore, valid throughout the system. Only processes started through a call to set the property of the corresponding instances. diff --git a/xml/System.Diagnostics/Switch.xml b/xml/System.Diagnostics/Switch.xml index 711c04aae19..61f5845f186 100644 --- a/xml/System.Diagnostics/Switch.xml +++ b/xml/System.Diagnostics/Switch.xml @@ -51,57 +51,57 @@ Provides an abstract base class to create new debugging and tracing switches. - class implements default behavior for switches, allowing you to change the switch level at run time. - - This class is the base class for the , , and classes. These switches meet most debugging and tracing needs. For more information about trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). - - You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - -- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. - -- To enable tracing using in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. - - To set the level of your switch in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: - -```xml - - - - - - - -``` - - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. - + class implements default behavior for switches, allowing you to change the switch level at run time. + + This class is the base class for the , , and classes. These switches meet most debugging and tracing needs. For more information about trace switches, see [Trace Switches](/dotnet/framework/debug-trace-profile/trace-switches). + + You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. + +- To enable debugging in C#, add the `/d:DEBUG` flag to the compiler command line when you compile your code, or you can add `#define DEBUG` to the top of your file. In Visual Basic, add the `/d:DEBUG=True` flag to the compiler command line. + +- To enable tracing using in C#, add the `/d:TRACE` flag to the compiler command line when you compile your code, or add `#define TRACE` to the top of your file. In Visual Basic, add the `/d:TRACE=True` flag to the compiler command line. + + To set the level of your switch in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. The configuration file should be formatted like the following example: + +```xml + + + + + + + +``` + + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Switch Example/CPP/remarks.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: - -## Examples - The following example shows how to define a new class with four levels of tracing that can be used to trace a call stack. You can use the switch to instrument your application to log each time the method is entered or exited. - - The first example creates the enumeration used to set the level of the switch. - + +## Examples + The following example shows how to define a new class with four levels of tracing that can be used to trace a call stack. You can use the switch to instrument your application to log each time the method is entered or exited. + + The first example creates the enumeration used to set the level of the switch. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Switch Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet1"::: - - The following example creates the new switch. The code implements a `Level` property to set the value of the new switch. `Level` calls the protected property that assigns the value to the new switch. This example also implements two assessor properties to get the assigned value of the switch. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet1"::: + + The following example creates the new switch. The code implements a `Level` property to set the value of the new switch. `Level` calls the protected property that assigns the value to the new switch. This example also implements two assessor properties to get the assigned value of the switch. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Switch Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet2"::: - - The following example creates a new switch in `Main`. It creates a new switch and assigns it a value. Then, depending on the switch settings, it outputs debugging messages for entering and leaving the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet2"::: + + The following example creates a new switch in `Main`. It creates a new switch and assigns it a value. Then, depending on the switch settings, it outputs debugging messages for entering and leaving the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Switch Example/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Switch Example/VB/source.vb" id="Snippet3"::: + ]]> @@ -180,26 +180,26 @@ The description for the switch. Initializes a new instance of the class. - object, the value of the `displayName` parameter is used to find initial switch settings. The default value is an empty string (""). - - Within the XML configuration file of a .NET Framework app, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. Dynamic changes to the configuration file are not detected while the application is executing. You must stop and restart an application before changes to the configuration file take effect. The configuration file should be formatted like the following example: - -```xml - - - - - - - - - - -``` - + object, the value of the `displayName` parameter is used to find initial switch settings. The default value is an empty string (""). + + Within the XML configuration file of a .NET Framework app, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. Dynamic changes to the configuration file are not detected while the application is executing. You must stop and restart an application before changes to the configuration file take effect. The configuration file should be formatted like the following example: + +```xml + + + + + + + + + + +``` + ]]> @@ -265,11 +265,11 @@ The default value for the switch. Initializes a new instance of the class, specifying the display name, description, and default value for the switch. - property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. - + property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. + ]]> @@ -318,19 +318,19 @@ Gets the custom switch attributes defined in the application configuration file. A containing the case-insensitive custom attributes for the trace switch. - property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. - - - -## Examples - The following code sample shows how to display the unrecognized attributes for a custom switch. - + property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + + + +## Examples + The following code sample shows how to display the unrecognized attributes for a custom switch. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet15"::: + ]]> @@ -402,11 +402,11 @@ Gets a description of the switch. The description of the switch. The default value is an empty string (""). - constructor. - + constructor. + ]]> @@ -462,19 +462,19 @@ Gets a name used to identify the switch. The name used to identify the switch. The default value is an empty string (""). - object, the finds initial switch settings. For more information, see the constructor and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches) in the Visual Studio documentation. - - - -## Examples - The following code example displays the display name for the switch in use by a trace source. This code example is part of a larger example that can be found in the class summary. - + object, the finds initial switch settings. For more information, see the constructor and [How to: Create, Initialize and Configure Trace Switches](/dotnet/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches) in the Visual Studio documentation. + + + +## Examples + The following code example displays the display name for the switch in use by a trace source. This code example is part of a larger example that can be found in the class summary. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet10"::: + ]]> @@ -534,19 +534,19 @@ Gets the custom attributes supported by the switch. A string array that contains the names of the custom attributes supported by the switch, or if there no custom attributes are supported. - method returns `null`. If a switch is added in a configuration file and custom attributes are specified that are not included in the string array returned by , a is thrown when the switch is loaded. - - - -## Examples - The following code sample shows an override of the method for a custom switch. - + method returns `null`. If a switch is added in a configuration file and custom attributes are specified that are not included in the string array returned by , a is thrown when the switch is loaded. + + + +## Examples + The following code sample shows an override of the method for a custom switch. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet34"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet34"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.TraceSource/VB/program.vb" id="Snippet34"::: + ]]> @@ -626,11 +626,11 @@ Invoked when the property is changed. - is invoked the first time a switch reads the value from the configuration file and is invoked again each time the switch's value is changed. - + is invoked the first time a switch reads the value from the configuration file and is invoked again each time the switch's value is changed. + ]]> @@ -674,11 +674,11 @@ Invoked when the property is changed. - property to an integer value which it uses to set the property. - + property to an integer value that it uses to set the property. + ]]> @@ -802,21 +802,21 @@ Gets or sets the value of the switch. A string representing the value of the switch. - method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. - + method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. + ]]> - The value is . - - -or- - - The value does not consist solely of an optional negative sign followed by a sequence of digits ranging from 0 to 9. - - -or- - + The value is . + + -or- + + The value does not consist solely of an optional negative sign followed by a sequence of digits ranging from 0 to 9. + + -or- + The value represents a number less than Int32.MinValue or greater than Int32.MaxValue. You should override the method and provide a conversion operation that sets the appropriate value for your switch. diff --git a/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml b/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml index 36abf21bc13..3e4e63b040b 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/AdamInstance.xml @@ -26,13 +26,13 @@ The class represents an AD LDS instance server. - [!NOTE] -> The class refers to Active Directory Application Mode (ADAM) which has been renamed to Active Directory Lightweight Directory Services (AD LDS). - +> The class refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). + ]]> @@ -60,11 +60,11 @@ Invokes the Knowledge Consistency Checker (KCC) that verifies the replication topology for this AD LDS instance. - A call to the underlying directory service resulted in an error. @@ -288,13 +288,13 @@ Returns an AD LDS instance for a specified context. An object that refers to the AD LDS instance that is found. - [!NOTE] -> The method refers to Active Directory Application Mode (ADAM) which has been renamed to Active Directory Lightweight Directory Services (AD LDS). - +> The method refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). + ]]> A connection to the target that was specified in the parameter could not be made. diff --git a/xml/System.DirectoryServices.ActiveDirectory/AdamInstanceCollection.xml b/xml/System.DirectoryServices.ActiveDirectory/AdamInstanceCollection.xml index 39e9b24918f..75e8c029745 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/AdamInstanceCollection.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/AdamInstanceCollection.xml @@ -26,13 +26,13 @@ The class is a read-only collection that contains objects. - [!NOTE] -> The class refers to Active Directory Application Mode (ADAM) which has been renamed to Active Directory Lightweight Directory Services (AD LDS). - +> The class refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). + ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/AdamRole.xml b/xml/System.DirectoryServices.ActiveDirectory/AdamRole.xml index 206980adf4b..0badc9e4920 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/AdamRole.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/AdamRole.xml @@ -19,13 +19,13 @@ Indicates specific roles of a object. - [!NOTE] -> The class refers to Active Directory Application Mode (ADAM) which has been renamed to Active Directory Lightweight Directory Services (AD LDS). - +> The class refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). + ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/AdamRoleCollection.xml b/xml/System.DirectoryServices.ActiveDirectory/AdamRoleCollection.xml index c0d42efeadf..f6835550dc1 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/AdamRoleCollection.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/AdamRoleCollection.xml @@ -20,13 +20,13 @@ The class is a read-only collection that contains items. - [!NOTE] -> The class refers to Active Directory Application Mode (ADAM) which has been renamed to Active Directory Lightweight Directory Services (AD LDS). - +> The class refers to Active Directory Application Mode (ADAM), which has been renamed to Active Directory Lightweight Directory Services (AD LDS). + ]]> diff --git a/xml/System.DirectoryServices.Protocols/LdapConnection.xml b/xml/System.DirectoryServices.Protocols/LdapConnection.xml index 808a3145b35..b103e2328b2 100644 --- a/xml/System.DirectoryServices.Protocols/LdapConnection.xml +++ b/xml/System.DirectoryServices.Protocols/LdapConnection.xml @@ -88,7 +88,7 @@ - A string specifying the server which can be a domain name, LDAP server name or dotted strings representing the IP address of the LDAP server. Optionally, this parameter may also include a port number, separated from the right end of the string by a colon (:). + A string specifying the server, which can be a domain name, LDAP server name, or dotted strings representing the IP address of the LDAP server. Optionally, this parameter can also include a port number, separated from the right end of the string by a colon (:). The constructor creates an instance of the class using the specified server. To be added. Failed to create a connection block or to open a connection to server. diff --git a/xml/System.EnterpriseServices/ServiceConfig.xml b/xml/System.EnterpriseServices/ServiceConfig.xml index 31d6c54d462..00bd98f0a4b 100644 --- a/xml/System.EnterpriseServices/ServiceConfig.xml +++ b/xml/System.EnterpriseServices/ServiceConfig.xml @@ -24,11 +24,11 @@ Specifies and configures the services that are to be active in the domain which is entered when calling or creating an . This class cannot be inherited. - and allow you to use the services configured by with no need to tie those services to a component. - + and allow you to use the services configured by with no need to tie those services to a component. + ]]> @@ -50,34 +50,34 @@ Initializes a new instance of the class, setting the properties to configure the desired services. - . - -|Item|Description| -|----------|-----------------| -|`Binding`|| -|`BringYourOwnTransaction`|`null`| -|`COMTIIntrinsicsEnabled`|`false`| -|`IISIntrinsicsEnabled`|`false`| -|`Inheritance`|| -|`IsolationLevel`|| -|`PartitionId`|A zero GUID.| -|`PartitionOption`|| -|`SxsDirectory`|`null`| -|`SxsName`|`null`| -|`SxsOption`|| -|`Synchronization`|| -|`ThreadPool`|| -|`TipUrl`|`null`| -|`TrackingAppName`|`null`| -|`TrackingComponentName`|`null`| -|`TrackingEnabled`|`false`| -|`Transaction`|| -|`TransactionDescription`|`null`| -|`TransactionTimeout`|The system default| - + . + +|Item|Description| +|----------|-----------------| +|`Binding`|| +|`BringYourOwnTransaction`|`null`| +|`COMTIIntrinsicsEnabled`|`false`| +|`IISIntrinsicsEnabled`|`false`| +|`Inheritance`|| +|`IsolationLevel`|| +|`PartitionId`|A zero GUID.| +|`PartitionOption`|| +|`SxsDirectory`|`null`| +|`SxsName`|`null`| +|`SxsOption`|| +|`Synchronization`|| +|`ThreadPool`|| +|`TipUrl`|`null`| +|`TrackingAppName`|`null`| +|`TrackingComponentName`|`null`| +|`TrackingEnabled`|`false`| +|`Transaction`|| +|`TransactionDescription`|`null`| +|`TransactionTimeout`|The system default| + ]]> @@ -105,11 +105,11 @@ Gets or sets the binding option, which indicates whether all work submitted by the activity is to be bound to only one single-threaded apartment (STA). One of the values. The default is . - has no impact on the multithreaded apartment (MTA). This property is used to set the thread pool binding only when creating a . An error is returned if an attempt is made to set the thread pool binding when calling . - + has no impact on the multithreaded apartment (MTA). This property is used to set the thread pool binding only when creating a . An error is returned if an attempt is made to set the thread pool binding when calling . + ]]> @@ -134,13 +134,13 @@ Gets or sets a that represents an existing transaction that supplies the settings used to run the transaction identified by . A . The default is . - (BYOT) identifies a transaction that supplies the context for the transaction. When you bring your own transaction, that transaction's settings override the other transaction settings in the object. The default value for is `null`. - - For more information on BYOT, see . - + (BYOT) identifies a transaction that supplies the context for the transaction. When you bring your own transaction, that transaction's settings override the other transaction settings in the object. The default value for is `null`. + + For more information on BYOT, see . + ]]> @@ -167,13 +167,13 @@ Gets or sets a that represents an existing transaction that supplies the settings used to run the transaction identified by . An . The default is . - (BYOT) identifies a transaction that supplies the context for the transaction. When you bring your own transaction, that transaction's settings override the other transaction settings in the object. The default value for is `null`. - - For more information on BYOT, see . - + (BYOT) identifies a transaction that supplies the context for the transaction. When you bring your own transaction, that transaction's settings override the other transaction settings in the object. The default value for is `null`. + + For more information on BYOT, see . + ]]> @@ -201,13 +201,13 @@ if COMTI intrinsics are enabled; otherwise, . The default is . - @@ -234,11 +234,11 @@ if IIS intrinsics are enabled; otherwise, . The default is . - @@ -287,11 +287,11 @@ Gets or sets the isolation level of the transaction. One of the values. The default is . - is ignored if the enclosed code would not otherwise run in a transaction. - + is ignored if the enclosed code would not otherwise run in a transaction. + ]]> @@ -363,13 +363,13 @@ Gets or sets the directory for the side-by-side assembly for the enclosed work. The name of the directory to be used for the side-by-side assembly. The default value is . - . - - You must set the property, if you create a new side-by-side assembly by setting the property to . - + . + + You must set the property, if you create a new side-by-side assembly by setting the property to . + ]]> @@ -461,7 +461,7 @@ System.EnterpriseServices.ThreadPoolOption - Gets or sets a value that indicates the thread pool which runs the work submitted by the activity. + Gets or sets a value that indicates the thread pool that runs the work submitted by the activity. One of the values. The default is . To be added. @@ -487,11 +487,11 @@ Gets or sets the Transaction Internet Protocol (TIP) URL that allows the enclosed code to run in an existing transaction. A TIP URL. The default value is . - is similar to the property but allows the enclosed code to run as an existing transaction that is specified by a TIP URL. - + is similar to the property but allows the enclosed code to run as an existing transaction that is specified by a TIP URL. + ]]> @@ -517,13 +517,13 @@ Gets or sets a text string that corresponds to the application ID under which tracker information is reported. The application ID under which tracker information is reported. The default value is . - . - - For more information, see . - + . + + For more information, see . + ]]> @@ -575,11 +575,11 @@ if tracking is enabled; otherwise, . The default is . - @@ -628,11 +628,11 @@ Gets or sets the name that is used when transaction statistics are displayed. The name used when transaction statistics are displayed. The default value is . - is used to describe the transaction. - + is used to describe the transaction. + ]]> diff --git a/xml/System.Formats.Asn1/AsnDecoder.xml b/xml/System.Formats.Asn1/AsnDecoder.xml index 793908549a5..81f13bb2abe 100644 --- a/xml/System.Formats.Asn1/AsnDecoder.xml +++ b/xml/System.Formats.Asn1/AsnDecoder.xml @@ -110,7 +110,7 @@ The buffer containing encoded data. The encoding constraints to use when interpreting the data. - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. This parameter is treated as uninitialized. @@ -139,13 +139,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -205,13 +205,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -280,24 +280,24 @@ is not defined. - + -or- - + is not a known character string type. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The string did not successfully decode. @@ -430,13 +430,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -505,28 +505,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was declared with . - + -or- - + . is , but . is not correct for @@ -603,28 +603,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was declared with . - + -or- - + . is , but . is not correct for @@ -680,13 +680,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -745,13 +745,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -810,13 +810,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -888,13 +888,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -963,28 +963,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was not declared with - + -or- - + . is , but . is not correct for @@ -1058,7 +1058,7 @@ with bits increasing in value until the least significant bit of the first byte, proceeding with the most significant bit of the second byte, and so on. Under this scheme, the following ASN.1 type declaration and C# enumeration can be used together: - + KeyUsage ::= BIT STRING { digitalSignature (0), @@ -1086,7 +1086,7 @@ DecipherOnly = 1 << (8), } - + While the example here uses the KeyUsage NamedBitList from RFC 3280 (4.2.1.3), the example enum uses values that are different from @@ -1097,28 +1097,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was not declared with - + -or- - + . is , but . is not correct for @@ -1171,13 +1171,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1242,13 +1242,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1314,13 +1314,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1392,13 +1392,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1476,13 +1476,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1543,20 +1543,20 @@ To be added. is not defined. - + -or- - + is not in the range [99, 9999]. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1652,7 +1652,7 @@ The buffer in which to write. The encoding constraints to use when interpreting the data. - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. This parameter is treated as uninitialized. @@ -1687,13 +1687,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1701,9 +1701,9 @@ , but . is not correct for the method. - + -or- - + overlaps . @@ -1769,24 +1769,24 @@ is not defined. - + -or- - + is not a known character string type. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The string did not successfully decode. @@ -1858,13 +1858,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1872,9 +1872,9 @@ , but . is not a character string tag type. - + -or- - + overlaps . @@ -2009,13 +2009,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2081,13 +2081,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2156,13 +2156,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2170,9 +2170,9 @@ , but . is not correct for the method. - + -or- - + overlaps . @@ -2209,7 +2209,7 @@ The buffer containing encoded data. The encoding constraints to use when interpreting the data. - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. This parameter is treated as uninitialized. @@ -2240,13 +2240,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2317,13 +2317,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2390,13 +2390,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2469,13 +2469,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2547,13 +2547,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. diff --git a/xml/System.Formats.Asn1/AsnReader.xml b/xml/System.Formats.Asn1/AsnReader.xml index 4c2b4923ae8..12d988ecd06 100644 --- a/xml/System.Formats.Asn1/AsnReader.xml +++ b/xml/System.Formats.Asn1/AsnReader.xml @@ -56,7 +56,7 @@ This constructor does not evaluate for correctness. Any correctness checks are done as part of member methods. - + This constructor does not copy . The caller is responsible for ensuring that the values do not change until the reader is finished. @@ -259,7 +259,7 @@ - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. @@ -276,13 +276,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -329,13 +329,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -392,17 +392,17 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The string did not successfully decode. @@ -484,13 +484,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -543,28 +543,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was declared with . - + -or- - + . is , but . is not correct for @@ -628,28 +628,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was declared with . - + -or- - + . is , but . is not correct for @@ -692,13 +692,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -744,13 +744,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -797,13 +797,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -847,13 +847,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -901,28 +901,28 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was not declared with - + -or- - + . is , but . is not correct for @@ -984,7 +984,7 @@ with bits increasing in value until the least significant bit of the first byte, proceeding with the most significant bit of the second byte, and so on. Under this scheme, the following ASN.1 type declaration and C# enumeration can be used together: - + KeyUsage ::= BIT STRING { digitalSignature (0), @@ -1012,7 +1012,7 @@ DecipherOnly = 1 << (8), } - + While the example here uses the KeyUsage NamedBitList from RFC 3280 (4.2.1.3), the example enum uses values that are different from @@ -1020,28 +1020,28 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The encoded value is too big to fit in a value. is not an enum type. - + -or- - + was not declared with - + -or- - + . is , but . is not correct for @@ -1081,13 +1081,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1132,13 +1132,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1186,13 +1186,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1245,13 +1245,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1305,13 +1305,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1369,13 +1369,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1423,13 +1423,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1481,13 +1481,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1589,7 +1589,7 @@ The buffer in which to write. - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. @@ -1611,13 +1611,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1683,17 +1683,17 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. - + -or- - + The string did not successfully decode. @@ -1752,13 +1752,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1812,13 +1812,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1871,13 +1871,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1933,13 +1933,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -1977,7 +1977,7 @@ - On success, receives the number of bits in the last byte which were reported as + On success, receives the number of bits in the last byte that were reported as "unused" by the writer. @@ -1998,13 +1998,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2059,13 +2059,13 @@ The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2117,13 +2117,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2183,13 +2183,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. @@ -2248,13 +2248,13 @@ To be added. The next value does not have the correct tag. - + -or- - + The length encoding is not valid under the current encoding rules. - + -or- - + The contents are not valid under the current encoding rules. diff --git a/xml/System.Formats.Asn1/AsnWriter.xml b/xml/System.Formats.Asn1/AsnWriter.xml index a0d4f2dea3b..b2cf15a6e1b 100644 --- a/xml/System.Formats.Asn1/AsnWriter.xml +++ b/xml/System.Formats.Asn1/AsnWriter.xml @@ -129,17 +129,17 @@ A or has not been closed via or . - + -or- - + This writer is empty. - + -or- - + This writer represents more than one top-level value. - + -or- - + This writer's value is encoded in a manner that is not compatible with the ruleset for the destination writer. @@ -626,7 +626,7 @@ Begin writing an Octet String value with a specified tag. - A disposable value which will automatically call . + A disposable value that will automatically call . This method is just an accelerator for writing an Octet String value where the @@ -668,7 +668,7 @@ Begin writing a Sequence with a specified tag. - A disposable value which will automatically call . + A disposable value that will automatically call . To be added. @@ -708,7 +708,7 @@ Begin writing a Set-Of with a specified tag. - A disposable value which will automatically call . + A disposable value that will automatically call . In and modes, @@ -863,13 +863,13 @@ , but . is not correct for the method. - + -or- - + has length 0 and is not 0 - + -or- - + is not empty and any of the bits identified by is set. @@ -956,9 +956,9 @@ To be added. is not a restricted character string encoding type. - + -or- - + is a restricted character string encoding type that is not currently supported by this method. @@ -1012,9 +1012,9 @@ is is not a restricted character string encoding type. - + -or- - + is a restricted character string encoding type that is not currently supported by this method. @@ -1061,9 +1061,9 @@ could not be read under the current encoding rules. - + -or- - + has data beyond the end of the first value. @@ -1108,13 +1108,13 @@ , but . is not correct for the method. - + -or- - + is not a boxed enum value. - + -or- - + the unboxed type of is declared []. @@ -1173,13 +1173,13 @@ , but . is not correct for the method. - + -or- - + is not an enum. - + -or- - + is declared []. @@ -1337,9 +1337,9 @@ To be added. The 9 most significant bits are all set. - + -or- - + The 9 most significant bits are all unset. @@ -1505,13 +1505,13 @@ , but . is not correct for the method. - + -or- - + is not a boxed enum value. - + -or- - + the unboxed type of is not declared []. @@ -1571,13 +1571,13 @@ , but . is not correct for the method. - + -or- - + is not an enum value. - + -or- - + is not declared []. @@ -1653,9 +1653,9 @@ , but . is not correct for the method. - + -or- - + is not a valid dotted decimal object identifier. @@ -1696,9 +1696,9 @@ , but . is not correct for the method. - + -or- - + is not a valid dotted decimal object identifier. diff --git a/xml/System.IO.Packaging/Package.xml b/xml/System.IO.Packaging/Package.xml index a218a197323..18c018732a6 100644 --- a/xml/System.IO.Packaging/Package.xml +++ b/xml/System.IO.Packaging/Package.xml @@ -80,7 +80,7 @@ A ("digital signature") is a composition of parts and relationships representing a digital signature included with a . The digital signature identifies the originator and validates that the signed parts and relationships contained in the have not been modified. - Packages also support Digital Rights Management (DRM) which allows content elements in a to be encrypted with specific access rights granted to authorized users. + Packages also support Digital Rights Management (DRM), which allows content elements in a to be encrypted with specific access rights granted to authorized users. Based on the architecture, an is a package type designed for storing documents based on the open [XML Paper Specification (XPS)](https://www.ecma-international.org/publications-and-standards/standards/ecma-388/). diff --git a/xml/System.IO.Packaging/ZipPackage.xml b/xml/System.IO.Packaging/ZipPackage.xml index 9e3e05a6451..ea7d4d473d0 100644 --- a/xml/System.IO.Packaging/ZipPackage.xml +++ b/xml/System.IO.Packaging/ZipPackage.xml @@ -57,7 +57,7 @@ The example creates a package that contains a single document part which is defined as the package's root element by a package-level . - The package also contains an image part and a second which defines an association between the source document part and the target image part. (The image is a resource that is used with the document). + The package also contains an image part and a second that defines an association between the source document part and the target image part. (The image is a resource that is used with the document). :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/Package/Overview/PackageWrite.cs" id="Snippetpackagewritecreatepackage"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageWrite/visualbasic/packagewrite.vb" id="Snippetpackagewritecreatepackage"::: diff --git a/xml/System.IO/BufferedStream.xml b/xml/System.IO/BufferedStream.xml index 7fe99b5ea7a..c5388fdd3d0 100644 --- a/xml/System.IO/BufferedStream.xml +++ b/xml/System.IO/BufferedStream.xml @@ -424,7 +424,7 @@ The method to be called when the asynchronous write operation is completed. A user-provided object that distinguishes this particular asynchronous write request from other requests. Begins an asynchronous write operation. (Consider using instead.) - An object that references the asynchronous write which could still be pending. + An object that references the asynchronous write, which could still be pending. . diff --git a/xml/System.IO/EndOfStreamException.xml b/xml/System.IO/EndOfStreamException.xml index 248a3e2bbf9..21d2644f995 100644 --- a/xml/System.IO/EndOfStreamException.xml +++ b/xml/System.IO/EndOfStreamException.xml @@ -88,9 +88,7 @@ and classes on top of the class. diff --git a/xml/System.IO/FileNotFoundException.xml b/xml/System.IO/FileNotFoundException.xml index 2f8a46a63f9..887323800b5 100644 --- a/xml/System.IO/FileNotFoundException.xml +++ b/xml/System.IO/FileNotFoundException.xml @@ -82,7 +82,7 @@ diff --git a/xml/System.IO/IOException.xml b/xml/System.IO/IOException.xml index 86246feefde..199bd34919c 100644 --- a/xml/System.IO/IOException.xml +++ b/xml/System.IO/IOException.xml @@ -93,20 +93,14 @@ The Base Class Library includes the following types, each of which is a derived class of `IOException` : - - - - - - - - - Where appropriate, use these types instead of IOException. - uses the HRESULT COR_E_IO which has the value 0x80131620. - - + uses the HRESULT COR_E_IO, which has the value 0x80131620. ## Examples This code example is part of a larger example provided for the method. diff --git a/xml/System.IO/UnmanagedMemoryStream.xml b/xml/System.IO/UnmanagedMemoryStream.xml index a6c0bc5c715..62508619976 100644 --- a/xml/System.IO/UnmanagedMemoryStream.xml +++ b/xml/System.IO/UnmanagedMemoryStream.xml @@ -497,7 +497,7 @@ ## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to display the contents to the console. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to display the contents to the console. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -628,7 +628,7 @@ ## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -1579,7 +1579,7 @@ This method is equivalent to the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to read and display the contents to the console. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to read and display the contents to the console. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -2067,7 +2067,7 @@ If an exception occurs during the write operation, it will be set as the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method which checks the property before attempting to write the data to the stream. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: diff --git a/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml b/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml index 7b913b42e33..2bb2a01fe9d 100644 --- a/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml +++ b/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml @@ -16,15 +16,15 @@ Represents a single requested claim in a security token request (RST). - which is a collection of objects. The contents of the wst:Claims element is accessed through the property. - - A object represents a request for a claim, identified by its claim type (the property), to be present in the security token issued by the STS. The property indicates whether the claim is required in the issued token. - - For more information about the element that this class represents, see the version of the WS-Trust specification that applies to your scenario. - + , which is a collection of objects. The contents of the wst:Claims element is accessed through the property. + + A object represents a request for a claim, identified by its claim type (the property), to be present in the security token issued by the STS. The property indicates whether the claim is required in the issued token. + + For more information about the element that this class represents, see the version of the WS-Trust specification that applies to your scenario. + ]]> @@ -57,11 +57,11 @@ The URI that represents the claim type. Initializes a new instance of the class with the specified claim type. - property is set to `false` and the property is set to `null` in the new instance. This constructor creates a object that represents a request for a claim that is required in the response. - + property is set to `false` and the property is set to `null` in the new instance. This constructor creates a object that represents a request for a claim that is required in the response. + ]]> @@ -88,11 +88,11 @@ if the claim is optional in the response; otherwise, . Initializes a new instance of the class with the specified claim type and a value that indicates whether the claim is optional. - property is set to `null` in the new instance. - + property is set to `null` in the new instance. + ]]> @@ -142,11 +142,11 @@ Gets the type of the requested claim. The URI that represents the claim type. - @@ -171,11 +171,11 @@ if the claim is optional in the response; otherwise, . - @@ -199,11 +199,11 @@ Gets or sets the requested claim value. The value of the claim. - diff --git a/xml/System.IdentityModel.Protocols.WSTrust/RequestedProofToken.xml b/xml/System.IdentityModel.Protocols.WSTrust/RequestedProofToken.xml index 61c73a61e83..25e61ac49af 100644 --- a/xml/System.IdentityModel.Protocols.WSTrust/RequestedProofToken.xml +++ b/xml/System.IdentityModel.Protocols.WSTrust/RequestedProofToken.xml @@ -16,13 +16,13 @@ Represents the contents of a wst:RequestedProofToken element. - property contains the key. If the security token is a regular token, such as a SCT, then its session key will be the material which gets encrypted. When the wst:RequestedProofToken contains only a wst:ComputedKey element as in the case of combined entropy, the property holds its contents. - - For more information about the element that this class represents, see the version of the WS-Trust specification that applies to your scenario. - + property contains the key. If the security token is a regular token, such as a SCT, then its session key will be the material that gets encrypted. When the wst:RequestedProofToken contains only a wst:ComputedKey element as in the case of combined entropy, the property holds its contents. + + For more information about the element that this class represents, see the version of the WS-Trust specification that applies to your scenario. + ]]> @@ -55,11 +55,11 @@ An array of that contains the key material. Initializes a new instance of the class using the specified key material. - @@ -106,11 +106,11 @@ A string that contains a URI that indicates the algorithm used to compute the session key in the combined entropy case. Initializes a new instance of the class using the specified computed key algorithm. - @@ -138,11 +138,11 @@ A that represents the credentials used to encrypt the key material. Initializes a new instance of the class using the specified key material and encrypting credentials. - @@ -166,11 +166,11 @@ Gets the computed key algorithm used to calculate the session key in the combined entropy case. A string that contains a URI that indicates the computed key algorithm. - @@ -194,11 +194,11 @@ Gets the key in the case when the wst:RequestedProofToken element contains a key. A that represents the key, which can be either encrypted or clear text. - diff --git a/xml/System.IdentityModel.Tokens/Saml2SecurityTokenHandler.xml b/xml/System.IdentityModel.Tokens/Saml2SecurityTokenHandler.xml index 15874f00eca..effe60de2a3 100644 --- a/xml/System.IdentityModel.Tokens/Saml2SecurityTokenHandler.xml +++ b/xml/System.IdentityModel.Tokens/Saml2SecurityTokenHandler.xml @@ -16,15 +16,15 @@ Represents a security token handler that creates security tokens from SAML 2.0 Assertions. - class serializes and deserializes security tokens backed by SAML 2.0 Assertions into objects. Security token handlers are responsible for creating, reading, writing, and validating tokens. - - You can configure a security token service (STS) or relying party (RP) application to process SAML 2.0 Assertion-backed security tokens by adding an instance of the class to the object configured for the service (or application). This can be done either programmatically or in the configuration file. The handler itself is configured from the configuration specified for the collection through the collection's property when it is added to the collection. While it is possible to configure the handler individually by setting its property, this is not normally necessary; however, if the handler must be configured individually, the property should be set after the handler is added to the collection. - - For many scenarios, the class can be used as-is; however, the class provides many extension points through the methods it exposes. By deriving from the and overriding specific methods, you can modify the functionality of the token processing provided in the default implementation, or you can add processing for extensions to the SAML Assertion specification that may be needed in some custom scenarios. - + class serializes and deserializes security tokens backed by SAML 2.0 Assertions into objects. Security token handlers are responsible for creating, reading, writing, and validating tokens. + + You can configure a security token service (STS) or relying party (RP) application to process SAML 2.0 Assertion-backed security tokens by adding an instance of the class to the object configured for the service (or application). This can be done either programmatically or in the configuration file. The handler itself is configured from the configuration specified for the collection through the collection's property when it is added to the collection. While it is possible to configure the handler individually by setting its property, this is not normally necessary; however, if the handler must be configured individually, the property should be set after the handler is added to the collection. + + For many scenarios, the class can be used as-is; however, the class provides many extension points through the methods it exposes. By deriving from the and overriding specific methods, you can modify the functionality of the token processing provided in the default implementation, or you can add processing for extensions to the SAML Assertion specification that may be needed in some custom scenarios. + ]]> @@ -55,11 +55,11 @@ Initializes a new instance of the class with default security token requirements. - property is set to an instance of that is crated with the parameterless constructor. - + property is set to an instance of that is crated with the parameterless constructor. + ]]> @@ -115,10 +115,10 @@ Adds all of the delegates associated with the subject into the attribute collection. To be added. - is . - - -or- - + is . + + -or- + is . @@ -194,11 +194,11 @@ , which indicates that the handler can validate tokens of type . - @@ -247,13 +247,13 @@ Gets a value that indicates whether this handler can serialize tokens of type . - ; which indicates that the handler can serialize tokens of type . + , which indicates that the handler can serialize tokens of type . - @@ -327,11 +327,11 @@ Creates a object for the assertion. A object. The default is . - @@ -390,11 +390,11 @@ Creates a object from a token descriptor. A that contains the converted claims. - @@ -425,15 +425,15 @@ A to add to the assertion being created or to ignore the object (and not create a SAML 2.0 authentication statement). To be added. - is . - - -or- - + is . + + -or- + The property of is . - The subject of the (the property) contains claims with a claim type of either or but does not contain at least one claim of each type. - - -or- - + The subject of the (the property) contains claims with a claim type of either or but does not contain at least one claim of each type. + + -or- + The authentication method specified by the subject of the cannot be resolved to an absolute URI. @@ -494,13 +494,13 @@ Creates the conditions for the assertion. A object that contains the conditions for the assertion. - property of the `tokenDescriptor`. It will also generate an AudienceRestrictionCondition limiting consumption of the assertion to the property of the `tokenDescriptor`. - + property of the `tokenDescriptor`. It will also generate an AudienceRestrictionCondition limiting consumption of the assertion to the property of the `tokenDescriptor`. + ]]> @@ -528,13 +528,13 @@ Creates a name identifier that identifies the assertion issuer. A that represents the name identifier. - property of the `tokenDescriptor`. - + property of the `tokenDescriptor`. + ]]> @@ -620,11 +620,11 @@ Creates SAML 2.0 statements to be included in the assertion. An enumeration of that contains the statements. - @@ -708,11 +708,11 @@ Builds an XML formatted string from a collection of SAML 2.0 attributes that represent the Actor. A well-formed XML string constructed using the attributes. - \\...\, ...\...\" - + \\...\, ...\...\" + ]]> @@ -764,19 +764,19 @@ A that represents the SAML 2.0 security token (the token should be of type ) to be checked. Throws an exception if the specified token already exists in the token replay cache; otherwise the token is added to the cache. - object configured for this handler through the property of the object referenced through the property. - + object configured for this handler through the property of the object referenced through the property. + ]]> is . - The property is . - - -or- - + The property is . + + -or- + There is no configured under the property of the handler configuration (accessed through the property). cannot be cast as an instance of . @@ -832,11 +832,11 @@ Gets the token encrypting credentials. Override this method to change the token encrypting credentials. An that represents the token encrypting credentials. - property of the `tokenDescriptor`. - + property of the `tokenDescriptor`. + ]]> @@ -867,13 +867,13 @@ Gets the credentials for signing the assertion. A that represents the credentials for signing the assertion. - property of the `tokenDescriptor` to retrieve the credentials. - + property of the `tokenDescriptor` to retrieve the credentials. + ]]> @@ -903,15 +903,15 @@ Returns the time until which the token should be held in the token replay cache. A that represents the expiration time. - ) than Configuration.TokenReplayCacheExpirationPeriod. - + ) than Configuration.TokenReplayCacheExpirationPeriod. + ]]> @@ -959,11 +959,11 @@ Gets or sets the security token serializer that is used to serialize and deserialize key identifiers. A that represents the serializer. - objects. - + objects. + ]]> An attempt to set the value to occurs. @@ -1047,18 +1047,18 @@ The issuer. Creates claims from a SAML 2.0 attribute statement and adds them to the specified subject. - - is . - - -or- - + is . + + -or- + is . @@ -1089,10 +1089,10 @@ Creates claims from a SAML 2.0 authentication statement and adds them to the specified subject. To be added. - is . - - -or- - + is . + + -or- + is . @@ -1122,11 +1122,11 @@ The issuer. Creates claims from a SAML 2.0 authorization decision statement and adds them to the specified subject. - @@ -1158,10 +1158,10 @@ Creates claims from the SAML 2.0 subject and adds them to the specified subject. To be added. - is . - - -or- - + is . + + -or- + is . @@ -1245,11 +1245,11 @@ Reads the <saml:Advice> element. A that represents the Advice element that is read. - @@ -1306,11 +1306,11 @@ Reads the <saml:Attribute> element. A that represents the Assertion element that is read. - @@ -1423,11 +1423,11 @@ Reads the <saml:AuthnContext> element. A that represents the AuthnContext element that is read. - element. To handle by-value authentication context declarations, override this method. - + element. To handle by-value authentication context declarations, override this method. + ]]> @@ -1511,11 +1511,11 @@ Reads the <saml:Conditions> element. A that represents the Conditions element that is read. - elements, override this method. - + elements, override this method. + ]]> @@ -1711,11 +1711,11 @@ Reads the <saml:ProxyRestriction> element, or a <saml:Condition> element that specifies an xsi:type of saml:ProxyRestrictionType. A that represents the element that was read. - @@ -1774,11 +1774,11 @@ Reads the <saml:Statement> element. A that represents the Statement element that was read. - @@ -1808,11 +1808,11 @@ Reads the <saml:Subject> element. A that represents the Subject element that was read. - element. To handle encrypted IDs in the Subject, override this method. - + element. To handle encrypted IDs in the Subject, override this method. + ]]> @@ -1869,11 +1869,11 @@ Reads the <saml:SubjectConfirmationData> element. A that represents the SubjectConfirmationData element that was read. - @@ -1986,14 +1986,14 @@ Reads a SAML 2.0 token from the specified stream. An instance of . To be added. - The property is . - - -or- - - The property of the configuration specified by the property is . - - -or- - + The property is . + + -or- + + The property of the configuration specified by the property is . + + -or- + The property of the configuration specified by the property is . @@ -2205,11 +2205,11 @@ to check for Audience Restriction condition. Validates the specified object. - @@ -2236,11 +2236,11 @@ The SAML 2.0 subject confirmation data. Validates the specified object. - @@ -2268,11 +2268,11 @@ Validates the token data and returns its claims. The identities contained in the token. - @@ -2302,10 +2302,10 @@ Writes the <saml:Action> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2334,10 +2334,10 @@ Writes the <saml:Advice> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2366,19 +2366,19 @@ Serializes the specified SAML assertion to the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . - The property of the assertion specified by is either or has no elements. - - -or- - - There are no statements and no subject in the assertion specified by . (Both the property and the property are .) If an assertion does not contain statements, it must contain a subject. - - -or- - + The property of the assertion specified by is either or has no elements. + + -or- + + There are no statements and no subject in the assertion specified by . (Both the property and the property are .) If an assertion does not contain statements, it must contain a subject. + + -or- + The assertion specified by contains an authentication, attribute, or authorization decision statement and no subject - these statements require a subject. (The property contains a statement of type , , or and the property is ). The token encrypting credentials do not have a Symmetric Key specified. @@ -2408,10 +2408,10 @@ Writes the <saml:Attribute> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2440,10 +2440,10 @@ Writes the <saml:AttributeStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2473,11 +2473,11 @@ A that represents the attribute whose value is being written. Writes the saml:Attribute value. - @@ -2509,10 +2509,10 @@ Writes the <saml:AudienceRestriction> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2541,10 +2541,10 @@ Writes the <saml:AuthnContext> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2573,10 +2573,10 @@ Writes the <saml:AuthnStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2605,10 +2605,10 @@ Writes the <saml:AuthzDecisionStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2637,10 +2637,10 @@ Writes the <saml:Conditions> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2669,10 +2669,10 @@ Writes the <saml:Evidence> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2701,10 +2701,10 @@ Writes the <saml:Issuer> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2733,10 +2733,10 @@ Serializes a to the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2765,10 +2765,10 @@ Writes the <saml:NameID> element. To be added. - is . - - -or- - + is . + + -or- + is . The Saml2NameIdentifier encrypting credentials must have a Symmetric Key specified. @@ -2798,10 +2798,10 @@ Both <Issuer> and <NameID> are of NameIDType. This method writes the content of either one of those elements. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2830,10 +2830,10 @@ Writes the <saml:ProxyRestriction> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2862,10 +2862,10 @@ Writes the Signing <ds:KeyInfo> element using the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . The handler cannot serialize the key identifier specified by . @@ -2894,18 +2894,18 @@ The data to write. Writes a Saml2Statement. - , \, or \ element. To handle custom classes for writing a \ element, override this method. - + , \, or \ element. To handle custom classes for writing a \ element, override this method. + ]]> - is . - - -or- - + is . + + -or- + is . @@ -2934,10 +2934,10 @@ Writes the <saml:Subject> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2966,10 +2966,10 @@ Writes the <saml:SubjectConfirmation> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2997,18 +2997,18 @@ The data to write. Writes the <saml:SubjectConfirmationData> element. - - is . - - -or- - + is . + + -or- + is . @@ -3037,10 +3037,10 @@ Serializes the Subject <ds:KeyInfo> element using the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . @@ -3069,10 +3069,10 @@ Writes the <saml:SubjectLocality> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -3101,10 +3101,10 @@ Writes a Saml2 Token to the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . is not a object. diff --git a/xml/System.IdentityModel.Tokens/SamlSecurityTokenHandler.xml b/xml/System.IdentityModel.Tokens/SamlSecurityTokenHandler.xml index 91e24d8df47..45ab1109834 100644 --- a/xml/System.IdentityModel.Tokens/SamlSecurityTokenHandler.xml +++ b/xml/System.IdentityModel.Tokens/SamlSecurityTokenHandler.xml @@ -16,15 +16,15 @@ Represents a security token handler that creates security tokens from SAML 1.1 Assertions. - class serializes and deserializes security tokens backed by SAML 1.1 Assertions into objects. Security token handlers are responsible for creating, reading, writing, and validating tokens. - - You can configure a security token service (STS) or relying party (RP) application to process SAML 1.1 Assertion-backed security tokens by adding an instance of the class to the object configured for the service (or application). This can be done either programmatically or in the configuration file. The handler itself is configured from the configuration specified for the collection through the collection's property when it is added to the collection. While it is possible to configure the handler individually by setting its property, this is not normally necessary; however, if the handler must be configured individually, the property should be set after the handler is added to the collection. - - For many scenarios, the class can be used as-is; however, the class provides many extension points through the methods it exposes. By deriving from the and overriding specific methods, you can modify the functionality of the token processing provided in the default implementation, or you can add processing for extensions to the SAML Assertion specification that may be needed in some custom scenarios. - + class serializes and deserializes security tokens backed by SAML 1.1 Assertions into objects. Security token handlers are responsible for creating, reading, writing, and validating tokens. + + You can configure a security token service (STS) or relying party (RP) application to process SAML 1.1 Assertion-backed security tokens by adding an instance of the class to the object configured for the service (or application). This can be done either programmatically or in the configuration file. The handler itself is configured from the configuration specified for the collection through the collection's property when it is added to the collection. While it is possible to configure the handler individually by setting its property, this is not normally necessary; however, if the handler must be configured individually, the property should be set after the handler is added to the collection. + + For many scenarios, the class can be used as-is; however, the class provides many extension points through the methods it exposes. By deriving from the and overriding specific methods, you can modify the functionality of the token processing provided in the default implementation, or you can add processing for extensions to the SAML Assertion specification that may be needed in some custom scenarios. + ]]> @@ -55,11 +55,11 @@ Initializes a new instance of the class with default security token requirements. - property is set to an instance of that is created with the parameterless constructor. - + property is set to an instance of that is created with the parameterless constructor. + ]]> @@ -115,10 +115,10 @@ Adds all of the delegates associated with the ActAs subject into the attribute collection. To be added. - is . - - -or- - + is . + + -or- + is . @@ -208,11 +208,11 @@ , which indicates that the handler can validate tokens of type . - @@ -235,13 +235,13 @@ Gets a value that indicates whether this handler can serialize tokens of type . - ; which indicates that the handler can serialize tokens of type . + , which indicates that the handler can serialize tokens of type . - @@ -315,11 +315,11 @@ When overridden in a derived class, creates a object for the assertion. A object. The default is . - @@ -353,11 +353,11 @@ Creates a object by using the specified issuer, conditions, advice and statements. You can override this method to customize the parameters used to create the assertion. The SAML assertion that was created. - property is set to this value. The is set to . - + property is set to this value. The is set to . + ]]> @@ -418,11 +418,11 @@ Creates a object from a token descriptor. A that contains the converted claims. - @@ -455,10 +455,10 @@ The SAML authentication statement that was created. To be added. - is . - - -or- - + is . + + -or- + is . @@ -519,13 +519,13 @@ Creates the conditions for the assertion. A object that contains the conditions for the assertion. - property of the `tokenDescriptor`. It will also generate an AudienceRestrictionCondition limiting consumption of the assertion to the property of the `tokenDescriptor`. - + property of the `tokenDescriptor`. It will also generate an AudienceRestrictionCondition limiting consumption of the assertion to the property of the `tokenDescriptor`. + ]]> @@ -609,11 +609,11 @@ Creates SAML 1.1 statements to be included in the assertion. An enumeration of that contains the statements. - @@ -697,11 +697,11 @@ Builds an XML formatted string from a collection of SAML 1.1 attributes that represent the Actor. A well-formed XML string constructed using the attributes. - \\...\, ...\...\" - + \\...\, ...\...\" + ]]> @@ -729,11 +729,11 @@ Returns the SAML11 authentication method identifier that matches the specified normalized value for a SAML authentication method. The SAML11 authentication method identifier (URI) that matches the specified normalized identifier. If no matching SAML11 authentication method is found, the URI is returned unaltered. - method returns the SAML11 authentication method identifier that matches the specified normalized URI. For example, if is specified for `normalizedAuthenticationType`, the following URI is returned: `urn:oasis:names:tc:SAML:1.0:am:X509-PKI`. If a mapping does not exist for `normalizedAuthenticationType`, it is returned unaltered. - + method returns the SAML11 authentication method identifier that matches the specified normalized URI. For example, if is specified for `normalizedAuthenticationType`, the following URI is returned: `urn:oasis:names:tc:SAML:1.0:am:X509-PKI`. If a mapping does not exist for `normalizedAuthenticationType`, it is returned unaltered. + ]]> @@ -760,19 +760,19 @@ A that represents the SAML 1.1 security token (the token should be of type ) to be checked. Throws an exception if the specified token already exists in the token replay cache; otherwise the token is added to the cache. - object configured for this handler through the property of the object referenced through the property. - + object configured for this handler through the property of the object referenced through the property. + ]]> is . - The property is . - - -or- - + The property is . + + -or- + The property of the handler configuration (accessed through the property) is . cannot be cast as an instance of . @@ -828,11 +828,11 @@ Gets the token encrypting credentials. Override this method to change the token encrypting credentials. An that represents the token encrypting credentials. - property of the `tokenDescriptor`. - + property of the `tokenDescriptor`. + ]]> @@ -863,13 +863,13 @@ Gets the credentials for signing the assertion. A that represents the credentials for signing the assertion. - property of the `tokenDescriptor` to retrieve the credentials. - + property of the `tokenDescriptor` to retrieve the credentials. + ]]> @@ -899,15 +899,15 @@ Returns the time until which the token should be held in the token replay cache. A that represents the expiration time. - ) than Configuration.TokenReplayCacheExpirationPeriod. - + ) than Configuration.TokenReplayCacheExpirationPeriod. + ]]> @@ -955,11 +955,11 @@ Gets or sets the security token serializer that is used to serialize and deserialize key identifiers. A that represents the serializer. - objects. - + objects. + ]]> An attempt to set the value to occurs. @@ -1035,11 +1035,11 @@ Returns the normalized value that matches a SAML 1.1 authentication method identifier. The normalized value, which is one of the values. If no matching value exists, is returned, unaltered. - method returns the value that matches the specified SAML11 authentication method identifier. For example, if `urn:oasis:names:tc:SAML:1.0:am:X509-PKI` is specified for `saml11AuthenticationMethod`, is returned. If a mapping does not exist for `saml11AuthenticationMethod`, it is returned unaltered. - + method returns the value that matches the specified SAML11 authentication method identifier. For example, if `urn:oasis:names:tc:SAML:1.0:am:X509-PKI` is specified for `saml11AuthenticationMethod`, is returned. If a mapping does not exist for `saml11AuthenticationMethod`, it is returned unaltered. + ]]> @@ -1070,18 +1070,18 @@ The issuer. Creates claims from a SAML 1.1 attribute statement and adds them to the specified subject. - - is . - - -or- - + is . + + -or- + is . @@ -1112,10 +1112,10 @@ Creates claims from a SAML 1.1 authentication statement and adds them to the specified subject. To be added. - is . - - -or- - + is . + + -or- + is . @@ -1145,11 +1145,11 @@ The issuer. Creates claims from a SAML 1.1 authorization decision statement and adds them to the specified subject. - @@ -1264,11 +1264,11 @@ Reads the <saml:Advice> element. A that represents the Advice element that is read. - @@ -1325,11 +1325,11 @@ Reads the <saml:Attribute> element. A that represents the Assertion element that is read. - @@ -1554,11 +1554,11 @@ Reads the <saml:Conditions> element. A that represents the Conditions element that is read. - elements, override this method. - + elements, override this method. + ]]> @@ -1675,11 +1675,11 @@ Reads the <saml:Statement> element. A that represents the Statement element that was read. - @@ -1709,11 +1709,11 @@ Reads the <saml:Subject> element. A that represents the Subject element that was read. - element. To handle encrypted IDs in the Subject, override this method. - + element. To handle encrypted IDs in the Subject, override this method. + ]]> @@ -1770,14 +1770,14 @@ Reads a SAML 1.1 token from the specified stream. An instance of . To be added. - The property is . - - -or- - - The property of the configuration specified by the property is . - - -or- - + The property is . + + -or- + + The property of the configuration specified by the property is . + + -or- + The property of the configuration specified by the property is . @@ -1984,11 +1984,11 @@ to check for Audience Restriction condition. Validates the specified object. - @@ -2016,11 +2016,11 @@ Validates the token data and returns its claims. The identities contained in the token. - @@ -2050,10 +2050,10 @@ Writes the <saml:Action> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2082,10 +2082,10 @@ Writes the <saml:Advice> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2114,10 +2114,10 @@ Serializes the specified SAML assertion to the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . The token encrypting credentials do not have a Symmetric Key specified. @@ -2147,10 +2147,10 @@ Writes the <saml:Attribute> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2179,10 +2179,10 @@ Writes the <saml:AttributeStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2212,11 +2212,11 @@ A that represents the attribute whose value is being written. Writes the saml:Attribute value. - @@ -2248,10 +2248,10 @@ Writes the <saml:AudienceRestriction> element. To be added. - is . - - -or- - + is . + + -or- + is . The property of the specified in is or an empty collection. @@ -2281,10 +2281,10 @@ Writes the <saml:AuthnStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2313,10 +2313,10 @@ Writes the <saml:AuthorityBinding> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2345,10 +2345,10 @@ Writes the <saml:AuthzDecisionStatement> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2376,18 +2376,18 @@ The data to write. By default, only and are supported. Serializes the specified object. - or method to serialize the condition based on the type of specified. - + or method to serialize the condition based on the type of specified. + ]]> - is . - - -or- - + is . + + -or- + is . is not supported. . By default, only and are supported. @@ -2418,10 +2418,10 @@ Writes the <saml:Conditions> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2450,10 +2450,10 @@ Writes the <saml:DoNotCacheCondition> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2482,10 +2482,10 @@ Writes the <saml:Evidence> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2514,10 +2514,10 @@ Writes the Signing <ds:KeyInfo> element using the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . The handler cannot serialize the key identifier specified by . @@ -2546,18 +2546,18 @@ The data to write. Writes a SamlStatement. - , \, or \ element. To handle custom classes for writing a \ element, override this method. - + , \, or \ element. To handle custom classes for writing a \ element, override this method. + ]]> - is . - - -or- - + is . + + -or- + is . @@ -2586,10 +2586,10 @@ Writes the <saml:Subject> element. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2618,10 +2618,10 @@ Serializes the Subject <ds:KeyInfo> element using the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . @@ -2650,10 +2650,10 @@ Writes a Saml Token to the specified XML writer. To be added. - is . - - -or- - + is . + + -or- + is . is not a object. diff --git a/xml/System.IdentityModel.Tokens/SecurityKeyType.xml b/xml/System.IdentityModel.Tokens/SecurityKeyType.xml index 450b60226d2..3d270835194 100644 --- a/xml/System.IdentityModel.Tokens/SecurityKeyType.xml +++ b/xml/System.IdentityModel.Tokens/SecurityKeyType.xml @@ -40,24 +40,24 @@ Specifies the type of key that is associated with a security token. - enumeration to set the property. - - The `BearerKey` field is used with the property. - -### BearerKey Requires Wsu:Id or Transport Security with Message Credentials - In federation scenarios, an issued token is generally configured as an endorsing supporting token for message security between a client and the relying parties. However, when a Security Token Service (STS) issues a token with no key (BearerKey), WCF configures it as a supporting token (WCF cannot endorse without a key). This requires the issued token to be referenced in the signature. WCF currently uses the following: `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd:Id` as a reference mechanism (Wsu:Id). - - If an issued token does not have such an attribute, on a client, a is thrown with the text "Element to sign must have id". This happens when a SAML 1.1 token is used as an issued token (the Wsu:Id is not defined in the SAML 1.1 specification). - - To work around this situation, either use transport security with message credentials (for example, ), or an STS must add the `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd:Id` (Wsu:Id) to the issued token. - - Note that if the Wsu:Id is added to a SAML 1.1 token, the resulting XML does not comply to the SAML 1.1 specification. The alternative is to add a Wsu:Id to the `EncryptedData` which is a result of encrypting the issued token. This procedure complies with the SAML 1.1 specification, because the `EncryptedData` element supports the Wsu:Id attribute. - - So to be compliant with the specification, the bearer token must be encrypted by the STS. - + enumeration to set the property. + + The `BearerKey` field is used with the property. + +### BearerKey Requires Wsu:Id or Transport Security with Message Credentials + In federation scenarios, an issued token is generally configured as an endorsing supporting token for message security between a client and the relying parties. However, when a Security Token Service (STS) issues a token with no key (BearerKey), WCF configures it as a supporting token (WCF cannot endorse without a key). This requires the issued token to be referenced in the signature. WCF currently uses the following: `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd:Id` as a reference mechanism (Wsu:Id). + + If an issued token does not have such an attribute, on a client, a is thrown with the text "Element to sign must have id". This happens when a SAML 1.1 token is used as an issued token (the Wsu:Id is not defined in the SAML 1.1 specification). + + To work around this situation, either use transport security with message credentials (for example, ), or an STS must add the `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd:Id` (Wsu:Id) to the issued token. + + Note that if the Wsu:Id is added to a SAML 1.1 token, the resulting XML does not comply to the SAML 1.1 specification. The alternative is to add a Wsu:Id to the `EncryptedData` that is a result of encrypting the issued token. This procedure complies with the SAML 1.1 specification, because the `EncryptedData` element supports the Wsu:Id attribute. + + So to be compliant with the specification, the bearer token must be encrypted by the STS. + ]]> diff --git a/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml b/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml index 45fc88992ba..04ce38fd8eb 100644 --- a/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml +++ b/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml @@ -14,13 +14,13 @@ - Represents a number elements found in a which represent security tokens. + Represents a number elements found in a , which represent security tokens. - @@ -53,13 +53,13 @@ The security token that the new instance represents. Initializes a new instance of the class by using a object. - method is not supported by the new instance unless the method is overridden. - - If the `securityToken` parameter is an instance of then the property is set to the value of the property. - + method is not supported by the new instance unless the method is overridden. + + If the `securityToken` parameter is an instance of then the property is set to the value of the property. + ]]> @@ -129,11 +129,11 @@ Gets the security token that is represented by the current instance. The security token that the current instance represents. - object by using the constructor, then the method is called to return the security token. - + object by using the constructor, then the method is called to return the security token. + ]]> @@ -184,11 +184,11 @@ Gets the XML representation of the wrapped token. The XML representation of the token. - constructor. - + constructor. + ]]> @@ -219,10 +219,10 @@ The identities that are contained in the token. To be added. - is . - - -or- - + is . + + -or- + is . diff --git a/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml b/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml index e5bcf856dd4..382548beb11 100644 --- a/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml +++ b/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml @@ -16,13 +16,13 @@ Represents the key for an entry in a . - there are two indexes required. One is the context ID, represented by the property, that is unique across all session tokens. The other is the key generation, represented by the property, which is unique within a session token. When a session token is issued it has only a context ID. When the session token is renewed, the key generation is added. After renewal, the renewed session token is uniquely identifiable via the context ID and key generation. - - Objects of type are used as the indexes to the session token cache. An index will always have a valid property specified, but the property may be `null`, depending on whether the token has been renewed. There is also an optional which gives the endpoint to which the token is scoped. - + there are two indexes required. One is the context ID, represented by the property, that is unique across all session tokens. The other is the key generation, represented by the property, which is unique within a session token. When a session token is issued it has only a context ID. When the session token is renewed, the key generation is added. After renewal, the renewed session token is uniquely identifiable via the context ID and key generation. + + Objects of type are used as the indexes to the session token cache. An index will always have a valid property specified, but the property may be `null`, depending on whether the token has been renewed. There is also an optional that gives the endpoint to which the token is scoped. + ]]> @@ -71,11 +71,11 @@ Gets the context ID for the cache key. The context ID for the cache key. - property of the cached token. - + property of the cached token. + ]]> @@ -99,11 +99,11 @@ Gets the Endpoint ID to which this cache entry is scoped. The Endpoint ID to which this cache entry is scoped. - property of the cached token. - + property of the cached token. + ]]> @@ -132,11 +132,11 @@ if the specified object is the same as the current cache key; otherwise, . - is `true`, the property is not used in the comparison. - + is `true`, the property is not used in the comparison. + ]]> @@ -161,11 +161,11 @@ Returns a hash code for the current cache key. The hash code for the current cache key. - is `true`, the property is not used in generating the hash code. - + is `true`, the property is not used in generating the hash code. + ]]> @@ -190,11 +190,11 @@ to ignore key generation; otherwise, . - property is treated by the following methods and operators: , , , , and . - + property is treated by the following methods and operators: , , , , and . + ]]> @@ -218,11 +218,11 @@ Gets the key generation for the cache key. The key generation for the cache key. - property of the cached token. - + property of the cached token. + ]]> @@ -253,11 +253,11 @@ if the cache keys are equal; otherwise, . - is `true`, the property is not used in the comparison. - + is `true`, the property is not used in the comparison. + ]]> @@ -288,11 +288,11 @@ if the cache keys are not equal; otherwise, . - is `true`, the property is not used in the comparison. - + is `true`, the property is not used in the comparison. + ]]> @@ -317,11 +317,11 @@ Overrides to provide a unique identifier. The key in string form. - is `true`, the property is not used. - + is `true`, the property is not used. + ]]> diff --git a/xml/System.Linq.Expressions/BinaryExpression.xml b/xml/System.Linq.Expressions/BinaryExpression.xml index 8268efaf1aa..ca99287c50e 100644 --- a/xml/System.Linq.Expressions/BinaryExpression.xml +++ b/xml/System.Linq.Expressions/BinaryExpression.xml @@ -486,7 +486,7 @@ ## Remarks If CanReduce returns true, this should return a valid expression. - This method can return another node which itself must be reduced. + This method can return another node that itself must be reduced. ]]> diff --git a/xml/System.Linq.Expressions/Expression.xml b/xml/System.Linq.Expressions/Expression.xml index eb711d81fc7..e4e63951b46 100644 --- a/xml/System.Linq.Expressions/Expression.xml +++ b/xml/System.Linq.Expressions/Expression.xml @@ -9551,7 +9551,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - The which this will be associated with. + The that this will be associated with. Creates a representing a label without a default value. A without a default value. To be added. @@ -9722,7 +9722,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - The which this will be associated with. + The that this will be associated with. The value of this when the label is reached through regular control flow. Creates a representing a label with the given default value. A with the given default value. @@ -20051,7 +20051,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - Reduces this node to a simpler expression. If CanReduce returns true, this should return a valid expression. This method can return another node which itself must be reduced. + Reduces this node to a simpler expression. If CanReduce returns true, this should return a valid expression. This method can return another node that itself must be reduced. The reduced expression. To be added. @@ -20094,7 +20094,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - Reduces this node to a simpler expression. If CanReduce returns true, this should return a valid expression. This method can return another node which itself must be reduced. + Reduces this node to a simpler expression. If CanReduce returns true, this should return a valid expression. This method can return another node that itself must be reduced. The reduced expression. System.Linq.Expressions.LabelTarget - The which this label is associated with. - The which this label is associated with. + The that this label is associated with. + The that this label is associated with. To be added. diff --git a/xml/System.Linq.Expressions/LambdaExpression.xml b/xml/System.Linq.Expressions/LambdaExpression.xml index f8058949ab2..81a8acebb06 100644 --- a/xml/System.Linq.Expressions/LambdaExpression.xml +++ b/xml/System.Linq.Expressions/LambdaExpression.xml @@ -329,7 +329,7 @@ - A which will be used to hold the lambda's IL. + A that will be used to hold the lambda's IL. Compiles the lambda into a method definition. To be added. @@ -360,7 +360,7 @@ - A which will be used to hold the lambda's IL. + A that will be used to hold the lambda's IL. Debugging information generator used by the compiler to mark sequence points and annotate local variables. Compiles the lambda into a method definition and custom debug information. To be added. diff --git a/xml/System.Linq.Expressions/ListInitExpression.xml b/xml/System.Linq.Expressions/ListInitExpression.xml index bd7b697a908..cacf1982a2a 100644 --- a/xml/System.Linq.Expressions/ListInitExpression.xml +++ b/xml/System.Linq.Expressions/ListInitExpression.xml @@ -57,21 +57,21 @@ Represents a constructor call that has a collection initializer. - factory methods to create a . - - The value of the property of a is . - - - -## Examples - The following example creates a that represents the initialization of a new dictionary instance that has two key-value pairs. - + factory methods to create a . + + The value of the property of a is . + + + +## Examples + The following example creates a that represents the initialization of a new dictionary instance that has two key-value pairs. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet7"::: + ]]> @@ -346,13 +346,13 @@ Reduces the binary expression node to a simpler expression. The reduced expression. - diff --git a/xml/System.Linq.Expressions/MemberInitExpression.xml b/xml/System.Linq.Expressions/MemberInitExpression.xml index 3ae56db7783..82cfb2b8d93 100644 --- a/xml/System.Linq.Expressions/MemberInitExpression.xml +++ b/xml/System.Linq.Expressions/MemberInitExpression.xml @@ -57,21 +57,21 @@ Represents calling a constructor and initializing one or more members of the new object. - factory methods to create a . - - The value of the property of a is . - - - -## Examples - The following example creates a that represents the initialization of two members of a new object. - + factory methods to create a . + + The value of the property of a is . + + + +## Examples + The following example creates a that represents the initialization of two members of a new object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet9"::: + ]]> @@ -346,13 +346,13 @@ Reduces the to a simpler expression. The reduced expression. - diff --git a/xml/System.Linq.Expressions/UnaryExpression.xml b/xml/System.Linq.Expressions/UnaryExpression.xml index ef4726a72f5..b9a9c4a5c6d 100644 --- a/xml/System.Linq.Expressions/UnaryExpression.xml +++ b/xml/System.Linq.Expressions/UnaryExpression.xml @@ -57,33 +57,33 @@ Represents an expression that has a unary operator. - that has a specific node type. - -||Factory Method| -|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| -||| -||| -||| -||| -||| -||| -||| -||| -||| - - In addition, the methods can also be used to create a . These factory methods can be used to create a of any node type that represents a unary operation. The parameter of these methods that is of type specifies the desired node type. - - - -## Examples - The following example creates a object that represents the reference conversion of a non-nullable integer expression to the nullable integer type. - + that has a specific node type. + +||Factory Method| +|----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------| +||| +||| +||| +||| +||| +||| +||| +||| +||| + + In addition, the methods can also be used to create a . These factory methods can be used to create a of any node type that represents a unary operation. The parameter of these methods that is of type specifies the desired node type. + + + +## Examples + The following example creates a object that represents the reference conversion of a non-nullable integer expression to the nullable integer type. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.Expression/VB/Expression.vb" id="Snippet11"::: + ]]> @@ -219,11 +219,11 @@ if the node represents a lifted call; otherwise, . - @@ -270,11 +270,11 @@ if the operator's return type is lifted to a nullable type; otherwise, . - is `true`, the operator returns a nullable type and if the nullable operand evaluates to `null`, the operator returns `null`. - + is `true`, the operator returns a nullable type and if the nullable operand evaluates to `null`, the operator returns `null`. + ]]> @@ -471,13 +471,13 @@ Reduces the expression node to a simpler expression. The reduced expression. - diff --git a/xml/System.Linq/ParallelEnumerable.xml b/xml/System.Linq/ParallelEnumerable.xml index 242cb8e2efc..2755a66036f 100644 --- a/xml/System.Linq/ParallelEnumerable.xml +++ b/xml/System.Linq/ParallelEnumerable.xml @@ -787,7 +787,7 @@ The input sequence. Enables treatment of a data source as if it were ordered, overriding the default of unordered. AsOrdered may only be invoked on non-generic sequences returned by AsParallel, ParallelEnumerable.Range, and ParallelEnumerable.Repeat. - The source sequence which will maintain the original ordering in the subsequent query operators. + The source sequence that will maintain the original ordering in the subsequent query operators. The type of elements of . The input sequence. Enables treatment of a data source as if it were ordered, overriding the default of unordered. AsOrdered may only be invoked on generic sequences returned by AsParallel, ParallelEnumerable.Range, and ParallelEnumerable.Repeat. - The source sequence which will maintain the original ordering in the subsequent query operators. + The source sequence that will maintain the original ordering in the subsequent query operators. - This is the parameterless constructor for which is used internally by the WMI.NET Provider Extensions infrastructure. + This is the parameterless constructor for that's used internally by the WMI.NET Provider Extensions infrastructure. To be added. diff --git a/xml/System.Management.Instrumentation/ManagementMemberAttribute.xml b/xml/System.Management.Instrumentation/ManagementMemberAttribute.xml index 853fff1d112..13302c673bd 100644 --- a/xml/System.Management.Instrumentation/ManagementMemberAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementMemberAttribute.xml @@ -86,7 +86,7 @@ Gets or sets the name of the management attribute. - Returns a string which is the name of the management attribute. + The name of the management attribute. To be added. diff --git a/xml/System.Management/ManagementClass.xml b/xml/System.Management/ManagementClass.xml index b88bb4cae84..1b9e198df68 100644 --- a/xml/System.Management/ManagementClass.xml +++ b/xml/System.Management/ManagementClass.xml @@ -40,13 +40,13 @@ Initializes a new instance of the class. - @@ -69,21 +69,21 @@ Initializes a new instance of the class. This is the parameterless constructor. - variable with the parameterless constructor. The example lists the methods, properties, and qualifiers for the created class. - + variable with the parameterless constructor. The example lists the methods, properties, and qualifiers for the created class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass/cs/ManagementClass.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass/vb/ManagementClass.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass/vb/ManagementClass.vb" id="Snippet1"::: + ]]> @@ -110,22 +110,22 @@ A specifying the WMI class to which to bind. The parameter must specify a WMI class path. The class represents a CIM management class from WMI. CIM classes represent management information including hardware, software, processes, and so on. For more information about the CIM classes available in Windows, see CIM Classes. Initializes a new instance of the class. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers for the created class. - + variable with a constructor. The example lists the methods, properties, and qualifiers for the created class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-M/cs/ManagementClass-M.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M/vb/ManagementClass-M.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M/vb/ManagementClass-M.vb" id="Snippet1"::: + ]]> @@ -152,21 +152,21 @@ The path to the WMI class. The class represents a CIM management class from WMI. CIM classes represent management information including hardware, software, processes, and so on. For more information about the CIM classes available in Windows, see CIM Classes. Initializes a new instance of the class initialized to the given path. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers for the created class. - + variable with a constructor. The example lists the methods, properties, and qualifiers for the created class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-S/cs/ManagementClass-S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S/vb/ManagementClass-S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S/vb/ManagementClass-S.vb" id="Snippet1"::: + ]]> @@ -195,21 +195,21 @@ An representing the options to use when retrieving this class. Initializes a new instance of the class initialized to the given WMI class path using the specified options. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. - + variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-M_O/cs/ManagementClass-M_O.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M_O/vb/ManagementClass-M_O.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M_O/vb/ManagementClass-M_O.vb" id="Snippet1"::: + ]]> @@ -247,13 +247,13 @@ An instance of the class containing the source of the serialized stream associated with the new . Initializes a new instance of the class from the specified instances of the and classes. - @@ -282,21 +282,21 @@ An representing the options to use when retrieving the WMI class. Initializes a new instance of the class initialized to the given WMI class path using the specified options. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. - + variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-S_O/cs/ManagementClass-S_O.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S_O/vb/ManagementClass-S_O.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S_O/vb/ManagementClass-S_O.vb" id="Snippet1"::: + ]]> @@ -327,22 +327,22 @@ An that specifies the options to use when retrieving the WMI class. Initializes a new instance of the class for the specified WMI class in the specified scope and with the specified options. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. You must change the scope (namespace) in the code for the example to run correctly on your computer. - + variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. You must change the scope (namespace) in the code for the example to run correctly on your computer. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-M_M_O/cs/ManagementClass-M_M_O.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M_M_O/vb/ManagementClass-M_M_O.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-M_M_O/vb/ManagementClass-M_M_O.vb" id="Snippet1"::: + ]]> @@ -373,22 +373,22 @@ An that specifies the options to use when retrieving the WMI class. Initializes a new instance of the class for the specified WMI class, in the specified scope, and with the specified options. The class represents a Common Information Model (CIM) management class from WMI such as **Win32_LogicalDisk**, which can represent a disk drive, and **Win32_Process**, which represents a process such as Notepad.exe. - variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. You must change the scope (namespace) in the code for the example to run correctly on your computer. - + variable with a constructor. The example lists the methods, properties, and qualifiers (including the amended qualifiers) for the created class. You must change the scope (namespace) in the code for the example to run correctly on your computer. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass-S_S_O/cs/ManagementClass-S_S_O.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S_S_O/vb/ManagementClass-S_S_O.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass-S_S_O/vb/ManagementClass-S_S_O.vb" id="Snippet1"::: + ]]> @@ -416,14 +416,14 @@ Returns a copy of the object. The cloned object. - @@ -451,22 +451,22 @@ Initializes a new instance of the WMI class. A that represents a new instance of the WMI class. - () method is called. Before committing it, the key properties must be specified. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example shows how to initialize a variable with a constructor and then create a new instance of a WMI class. - + () method is called. Before committing it, the key properties must be specified. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example shows how to initialize a variable with a constructor and then create a new instance of a WMI class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_CreateInstance/cs/ManagementClass_CreateInstance.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_CreateInstance/vb/ManagementClass_CreateInstance.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_CreateInstance/vb/ManagementClass_CreateInstance.vb" id="Snippet1"::: + ]]> @@ -493,22 +493,22 @@ Gets an array containing all WMI classes in the inheritance hierarchy from this class to the top of the hierarchy. A string collection containing the names of all WMI classes in the inheritance hierarchy of this class. - variable with a constructor and then get all the classes in the inheritance hierarchy from the WMI class passed into the constructor, to the top of the hierarchy. - + variable with a constructor and then get all the classes in the inheritance hierarchy from the WMI class passed into the constructor, to the top of the hierarchy. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_Derivation/cs/ManagementClass_Derivation.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Derivation/vb/ManagementClass_Derivation.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Derivation/vb/ManagementClass_Derivation.vb" id="Snippet1"::: + ]]> @@ -539,22 +539,22 @@ Derives a new class from this class. A new that represents a new WMI class derived from the original class. - () method is explicitly called. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example shows how to initialize a variable with a constructor and then create a derived instance of a WMI class. - + () method is explicitly called. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example shows how to initialize a variable with a constructor and then create a derived instance of a WMI class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_Derive/cs/ManagementClass_Derive.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Derive/vb/ManagementClass_Derive.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Derive/vb/ManagementClass_Derive.vb" id="Snippet1"::: + ]]> @@ -567,13 +567,13 @@ Returns the collection of all instances of the class. - @@ -601,21 +601,21 @@ Returns the collection of all instances of the class. A collection of the objects representing the instances of the class. - variable with a constructor and then get all the instances of a WMI class. - + variable with a constructor and then get all the instances of a WMI class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances/cs/ManagementClass_GetInstances.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances/vb/ManagementClass_GetInstances.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances/vb/ManagementClass_GetInstances.vb" id="Snippet1"::: + ]]> @@ -646,21 +646,21 @@ Returns the collection of all instances of the class using the specified options. A collection of the objects representing the instances of the class, according to the specified options. - variable with a constructor and then get all the instances of a WMI class and its subclasses. - + variable with a constructor and then get all the instances of a WMI class and its subclasses. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-E/cs/ManagementClass_GetInstances-E.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-E/vb/ManagementClass_GetInstances-E.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-E/vb/ManagementClass_GetInstances-E.vb" id="Snippet1"::: + ]]> @@ -690,21 +690,21 @@ The object to handle the asynchronous operation's progress. Returns the collection of all instances of the class, asynchronously. - variable with a constructor and then get all the instances of a WMI class asynchronously. - + variable with a constructor and then get all the instances of a WMI class asynchronously. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-M/cs/ManagementClass_GetInstances-M.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-M/vb/ManagementClass_GetInstances-M.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetInstances-M/vb/ManagementClass_GetInstances-M.vb" id="Snippet1"::: + ]]> @@ -736,13 +736,13 @@ The specified additional options for getting the instances. Returns the collection of all instances of the class, asynchronously, using the specified options. - @@ -773,13 +773,13 @@ The location where serialized data will be stored and retrieved. Populates a with the data necessary to deserialize the field represented by this instance. - @@ -792,13 +792,13 @@ Retrieves classes related to the WMI class. - @@ -826,22 +826,22 @@ Retrieves classes related to the WMI class. A collection of the or objects that represents WMI classes or instances related to the WMI class. - variable with a constructor and then list all the classes related to the WMI class passed into the constructor. - + variable with a constructor and then list all the classes related to the WMI class passed into the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses/cs/ManagementClass_GetRelatedClasses.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses/vb/ManagementClass_GetRelatedClasses.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses/vb/ManagementClass_GetRelatedClasses.vb" id="Snippet1"::: + ]]> @@ -871,13 +871,13 @@ The object to handle the asynchronous operation's progress. Retrieves classes related to the WMI class, asynchronously. - @@ -908,13 +908,13 @@ Retrieves classes related to the WMI class. A collection of classes related to this class. - @@ -946,13 +946,13 @@ The name of the related class. Retrieves classes related to the WMI class, asynchronously, given the related class name. - @@ -986,7 +986,7 @@ The class from which resulting classes have to be derived. - The relationship type which resulting classes must have with the source class. + The relationship type that resulting classes must have with the source class. This qualifier must be present on the relationship. This qualifier must be present on the resulting classes. The resulting classes must have this role in the relationship. @@ -995,21 +995,21 @@ Retrieves classes related to the WMI class based on the specified options. A collection of classes related to this class. - method to list the related classes to the **CIM_LogicalDisk** class. For more information, see [CIM_LogicalDisk](/windows/win32/cimwin32prov/cim-logicaldisk). - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses-7/cs/ManagementClass_GetRelatedClasses-7.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses-7/vb/ManagementClass_GetRelatedClasses-7.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelatedClasses-7/vb/ManagementClass_GetRelatedClasses-7.vb" id="Snippet1"::: + ]]> @@ -1045,7 +1045,7 @@ Handler for progress and results of the asynchronous operation. The class from which resulting classes have to be derived. - The relationship type which resulting classes must have with the source class. + The relationship type that resulting classes must have with the source class. This qualifier must be present on the relationship. This qualifier must be present on the resulting classes. The resulting classes must have this role in the relationship. @@ -1053,13 +1053,13 @@ The options for retrieving the resulting classes. Retrieves classes related to the WMI class, asynchronously, using the specified options. - @@ -1072,13 +1072,13 @@ Retrieves relationship classes that relate the class to others. - @@ -1106,21 +1106,21 @@ Retrieves relationship classes that relate the class to others. A collection of *association classes* that relate the class to any other class. - method to list the relationship classes to the **CIM_LogicalDisk** class. For more information, see [CIM_LogicalDisk](/windows/win32/cimwin32prov/cim-logicaldisk). - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelationshipClasses/cs/ManagementClass_GetRelationshipClasses.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelationshipClasses/vb/ManagementClass_GetRelationshipClasses.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetRelationshipClasses/vb/ManagementClass_GetRelationshipClasses.vb" id="Snippet1"::: + ]]> @@ -1150,13 +1150,13 @@ The object to handle the asynchronous operation's progress. Retrieves relationship classes that relate the class to others, asynchronously. - @@ -1187,13 +1187,13 @@ Retrieves relationship classes that relate the class to others, where the endpoint class is the specified class. A collection of *association classes* that relate the class to the specified class. For more information about relationship classes, ASSOCIATORS OF Statement. - @@ -1225,14 +1225,14 @@ The WMI class to which all returned relationships should point. Retrieves relationship classes that relate the class to the specified WMI class, asynchronously. - @@ -1269,13 +1269,13 @@ Retrieves relationship classes that relate this class to others, according to specified options. A collection of *association classes* that relate this class to others, according to the specified options. For more information about relationship classes, ASSOCIATORS OF Statement. - @@ -1309,17 +1309,17 @@ The handler for progress and results of the asynchronous operation. The class from which all resulting relationship classes must derive. The qualifier which the resulting relationship classes must have. - The role which the source class must have in the resulting relationship classes. + The role that the source class must have in the resulting relationship classes. The options for retrieving the results. Retrieves relationship classes that relate the class according to the specified options, asynchronously. - @@ -1332,13 +1332,13 @@ Generates a strongly-typed class for a given WMI class. - @@ -1373,21 +1373,21 @@ Generates a strongly-typed class for a given WMI class. A representing the declaration for the strongly-typed class. - @@ -1423,21 +1423,21 @@ , if the method succeeded; otherwise, . - @@ -1450,13 +1450,13 @@ Returns the collection of all derived classes for the class. - @@ -1484,21 +1484,21 @@ Returns the collection of all subclasses for the class. A collection of the objects that represent the subclasses of the WMI class. - method to list the subclasses to the **CIM_LogicalDisk** class. For more information, see [CIM_LogicalDisk](/windows/win32/cimwin32prov/cim-logicaldisk). - + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses/cs/ManagementClass_GetSubclasses.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses/vb/ManagementClass_GetSubclasses.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses/vb/ManagementClass_GetSubclasses.vb" id="Snippet1"::: + ]]> @@ -1529,21 +1529,21 @@ Retrieves the subclasses of the class using the specified options. A collection of the objects representing the subclasses of the WMI class, according to the specified options. - variable with a constructor and then receive the subclasses of the WMI class passed into the constructor. - + variable with a constructor and then receive the subclasses of the WMI class passed into the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses-E/cs/ManagementClass_GetSubclasses-E.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses-E/vb/ManagementClass_GetSubclasses-E.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_GetSubClasses-E/vb/ManagementClass_GetSubclasses-E.vb" id="Snippet1"::: + ]]> @@ -1573,13 +1573,13 @@ The object to handle the asynchronous operation's progress. Returns the collection of all classes derived from this class, asynchronously. - @@ -1611,13 +1611,13 @@ The specified additional options to use in the derived class retrieval. Retrieves all classes derived from this class, asynchronously, using the specified options. - @@ -1644,21 +1644,21 @@ Gets or sets a collection of objects that represent the methods defined in the WMI class. A representing the methods defined in the WMI class. - variable with a constructor and then get all the methods in the WMI class passed into the constructor. - + variable with a constructor and then get all the methods in the WMI class passed into the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_Methods/cs/ManagementClass_Methods.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Methods/vb/ManagementClass_Methods.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Methods/vb/ManagementClass_Methods.vb" id="Snippet1"::: + ]]> @@ -1685,22 +1685,22 @@ Gets or sets the path of the WMI class to which the object is bound. The path of the object's class. - will be disconnected from any previously-bound WMI class. Reconnect to the new WMI class path. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example shows how to initialize a variable with a constructor and then get all the methods in the WMI class passed into the constructor. - + will be disconnected from any previously-bound WMI class. Reconnect to the new WMI class path. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example shows how to initialize a variable with a constructor and then get all the methods in the WMI class passed into the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementClass_Path/cs/ManagementClass_Path.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Path/vb/ManagementClass_Path.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_ManagementClass_Path/vb/ManagementClass_Path.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Management/WqlEventQuery.xml b/xml/System.Management/WqlEventQuery.xml index 0828c322493..7c8d2bc9c08 100644 --- a/xml/System.Management/WqlEventQuery.xml +++ b/xml/System.Management/WqlEventQuery.xml @@ -52,13 +52,13 @@ Initializes a new instance of the class. This is the parameterless constructor. - @@ -85,21 +85,21 @@ The string representing either the entire event query or the name of the event class to query. The object will try to parse the string as a valid event query. If unsuccessful, the parser will assume that the parameter represents an event class name. Initializes a new instance of the class based on the given query string or event class name. - by specifying a query and then initializes a by specifying an event. - + by specifying a query and then initializes a by specifying an event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S/cs/WqlEventQuery-S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S/vb/WqlEventQuery-S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S/vb/WqlEventQuery-S.vb" id="Snippet1"::: + ]]> @@ -128,13 +128,13 @@ The condition to apply to events of the specified class. Initializes a new instance of the class for the specified event class name, with the specified condition. - @@ -163,21 +163,21 @@ A value specifying the latency acceptable for receiving this event. This value is used in cases where there is no explicit event provider for the query requested, and WMI is required to poll for the condition. This interval is the maximum amount of time that can pass before notification of an event must be delivered. Initializes a new instance of the class for the specified event class, with the specified latency time. - by specifying an event and a time span value specifying the latency acceptable for receiving this event. - + by specifying an event and a time span value specifying the latency acceptable for receiving this event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T/cs/WqlEventQuery-S_T.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T/vb/WqlEventQuery-S_T.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T/vb/WqlEventQuery-S_T.vb" id="Snippet1"::: + ]]> @@ -208,13 +208,13 @@ The specified interval at which WMI sends one aggregate event, rather than many events. Initializes a new instance of the class with the specified event class name, condition, and grouping interval. - @@ -245,21 +245,21 @@ The condition to apply to events of the specified class. Initializes a new instance of the class with the specified event class name, polling interval, and condition. - @@ -292,13 +292,13 @@ The properties in the event class by which the events should be grouped. Initializes a new instance of the class with the specified event class name, condition, grouping interval, and grouping properties. - @@ -335,21 +335,20 @@ The condition to apply to the number of events. Initializes a new instance of the class with the specified event class name, condition, grouping interval, grouping properties, and specified number of events. - 15" which delivers aggregate events only if the number of **Win32_NTLogEvent** events received from the same source exceeds 15. - + 15", which delivers aggregate events only if the number of **Win32_NTLogEvent** events received from the same source exceeds 15. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T_S_T_S_S/cs/WqlEventQuery-S_T_S_T_S_S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T_S_T_S_S/vb/WqlEventQuery-S_T_S_T_S_S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery-S_T_S_T_S_S/vb/WqlEventQuery-S_T_S_T_S_S.vb" id="Snippet1"::: + ]]> @@ -376,13 +375,13 @@ Builds the query string according to the current property values. - @@ -410,13 +409,13 @@ Creates a copy of the object. The copied object. - @@ -444,25 +443,25 @@ Gets or sets the condition to be applied to events of the specified class. Returns a value containing the condition or conditions in the event query. - \ \ combined with logical operators. \ must represent a property defined on the event class specified in this query. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example initializes a new and displays the event query string. - + \ \ combined with logical operators. \ must represent a property defined on the event class specified in this query. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example initializes a new and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_Condition/cs/WqlEventQuery_Condition.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_Condition/vb/WqlEventQuery_Condition.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_Condition/vb/WqlEventQuery_Condition.vb" id="Snippet1"::: + ]]> @@ -489,25 +488,25 @@ Gets or sets the event class to query. Returns a value containing the name of the event class in the event query. - and displays the event query string. - + and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_EventClassName/cs/WqlEventQuery_EventClassName.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_EventClassName/vb/WqlEventQuery_EventClassName.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_EventClassName/vb/WqlEventQuery_EventClassName.vb" id="Snippet1"::: + ]]> @@ -534,25 +533,25 @@ Gets or sets properties in the event to be used for grouping events of the same type. Returns a containing the properties in the event to be used for grouping events of the same type. - and displays the event query string. - + and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupByPropertyList/cs/WqlEventQuery_GroupByPropertyList.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupByPropertyList/vb/WqlEventQuery_GroupByPropertyList.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupByPropertyList/vb/WqlEventQuery_GroupByPropertyList.vb" id="Snippet1"::: + ]]> @@ -579,25 +578,25 @@ Gets or sets the interval to be used for grouping events of the same type. Returns a value containing the interval used for grouping events of the same type. - and displays the event query string. - + and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupWithinInterval/cs/WqlEventQuery_GroupWithinInterval.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupWithinInterval/vb/WqlEventQuery_GroupWithinInterval.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_GroupWithinInterval/vb/WqlEventQuery_GroupWithinInterval.vb" id="Snippet1"::: + ]]> @@ -624,25 +623,25 @@ Gets or sets the condition to be applied to the aggregation of events, based on the number of events received. Returns a value containing the condition applied to the aggregation of events, based on the number of events received. - \". - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example initializes a new and displays the event query string. - + \". + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example initializes a new and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_HavingCondition/cs/WqlEventQuery_HavingCondition.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_HavingCondition/vb/WqlEventQuery_HavingCondition.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_HavingCondition/vb/WqlEventQuery_HavingCondition.vb" id="Snippet1"::: + ]]> @@ -672,13 +671,13 @@ The query string to be parsed. Parses the query string and sets the property values accordingly. - @@ -705,16 +704,16 @@ Gets the language of the query. Returns a value that contains the query language that the query is written in. - @@ -741,24 +740,24 @@ Gets or sets the string representing the query. Returns a value containing the query. - and displays the event query string. - + and displays the event query string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_QueryString/cs/WqlEventQuery_QueryString.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_QueryString/vb/WqlEventQuery_QueryString.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_QueryString/vb/WqlEventQuery_QueryString.vb" id="Snippet1"::: + ]]> @@ -785,27 +784,27 @@ Gets or sets the polling interval to be used in this query. Returns a value containing the polling interval used in the event query. - value if polling is required. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example initializes a new that represents the query: "SELECT * FROM __InstanceCreationEvent *WITHIN* 1 WHERE TargetInstance ISA 'Win32_Process'". - + value if polling is required. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example initializes a new that represents the query: "SELECT * FROM __InstanceCreationEvent *WITHIN* 1 WHERE TargetInstance ISA 'Win32_Process'". + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_WqlEventQuery_WithinInterval/cs/WqlEventQuery_WithinInterval.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_WithinInterval/vb/WqlEventQuery_WithinInterval.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WindowsServer/wminet_WqlEventQuery_WithinInterval/vb/WqlEventQuery_WithinInterval.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Messaging/MessageQueueAccessControlEntry.xml b/xml/System.Messaging/MessageQueueAccessControlEntry.xml index 5077397af25..ea6d89b6e83 100644 --- a/xml/System.Messaging/MessageQueueAccessControlEntry.xml +++ b/xml/System.Messaging/MessageQueueAccessControlEntry.xml @@ -18,21 +18,21 @@ Specifies access rights for a trustee (user, group, or computer) to perform Message Queuing tasks. - class to specify rights to apply to a trustee. These rights include peeking, receiving, or sending messages; viewing or modifying queue properties or permissions; and deleting queues. The class's method provides overloads for passing an instance of this class directly into the method, or adding it to an instance of so that you can add rights for more than one trustee at a time. The new access right is appended to the end of the queue's discretionary access control list (DACL), which identifies the users and groups that can access the queue. - - There are some exceptions to this generalization about where the new right is added and its effects. For more information, see . - - An overload of the constructor allows you specify a member to indicate whether to allow or deny rights to the trustee. The order in which rights are allowed or denied in the resource's DACL affects whether the trustee has the specified rights. For example, if rights have already been granted to the trustee and you later add an entry that denies them, the system finds the granted rights first, so the user is granted rights you might have intended they be denied. You can use two entry types to override this behavior: `Set` and `Revoke`. For more information about controlling the way in which access rights are determined, see the enumeration topic. - - The class is associated with security based on access control lists (ACLs), which you can use to give users access to the Message Queuing system itself. This is different from code access security, which is implemented through the and related classes. Message Queuing code access security defines queue-specific operations or queue access that an application might require which is subject to security control; it does not represent a right for the application to perform these operations or receive access in and of itself. See the topic [Code Access Security](/dotnet/framework/misc/code-access-security) for more information about code access security. - - To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. - - You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . - + class to specify rights to apply to a trustee. These rights include peeking, receiving, or sending messages; viewing or modifying queue properties or permissions; and deleting queues. The class's method provides overloads for passing an instance of this class directly into the method, or adding it to an instance of so that you can add rights for more than one trustee at a time. The new access right is appended to the end of the queue's discretionary access control list (DACL), which identifies the users and groups that can access the queue. + + There are some exceptions to this generalization about where the new right is added and its effects. For more information, see . + + An overload of the constructor allows you specify a member to indicate whether to allow or deny rights to the trustee. The order in which rights are allowed or denied in the resource's DACL affects whether the trustee has the specified rights. For example, if rights have already been granted to the trustee and you later add an entry that denies them, the system finds the granted rights first, so the user is granted rights you might have intended they be denied. You can use two entry types to override this behavior: `Set` and `Revoke`. For more information about controlling the way in which access rights are determined, see the enumeration topic. + + The class is associated with security based on access control lists (ACLs), which you can use to give users access to the Message Queuing system itself. This is different from code access security, which is implemented through the and related classes. Message Queuing code access security defines queue-specific operations or queue access that an application might require that is subject to security control; it does not represent a right for the application to perform these operations or receive access in and of itself. See the topic [Code Access Security](/dotnet/framework/misc/code-access-security) for more information about code access security. + + To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. + + You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . + ]]> @@ -74,13 +74,13 @@ A bitwise combination of the values which defines the combination of rights to grant to the trustee. Initializes a new instance of the class, granting the specified Message Queuing access rights to the specified trustee. - bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. - - Pass this instance of directly into an overload of the method to grant rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. - + bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. + + Pass this instance of directly into an overload of the method to grant rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. + ]]> @@ -114,15 +114,15 @@ One of the values, which specifies whether to allow, deny, set or revoke the specified rights. Initializes a new instance of the class, with the specified trustee and Message Queuing access rights. The type of access (such as or ) is defined by the entry type you pass in. - bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. - - For more information about granting or denying rights, see the topic. For two members, `Allow` and `Deny`, there may be preexisting and possibly contradictory access rights, so the order in which the rights appear in the queue's discretionary access control list (DACL) affects whether the right is ultimately granted. Two other members, `Set` and `Revoke`, overwrite any existing rights. Use the member whose behavior is applicable to your application. - - Pass this instance of directly into an overload of the method to grant or deny rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. - + bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. + + For more information about granting or denying rights, see the topic. For two members, `Allow` and `Deny`, there may be preexisting and possibly contradictory access rights, so the order in which the rights appear in the queue's discretionary access control list (DACL) affects whether the right is ultimately granted. Two other members, `Set` and `Revoke`, overwrite any existing rights. Use the member whose behavior is applicable to your application. + + Pass this instance of directly into an overload of the method to grant or deny rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. + ]]> @@ -152,11 +152,11 @@ Gets or sets the set of Message Queuing-specific rights to apply to the trustee. A bitwise combination of the members. The default is defined by the parameter passed into the constructor. - property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . - + property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . + ]]> diff --git a/xml/System.Numerics.Tensors/TensorPrimitives.xml b/xml/System.Numerics.Tensors/TensorPrimitives.xml index e2f7c14604d..fad347dc4ce 100644 --- a/xml/System.Numerics.Tensors/TensorPrimitives.xml +++ b/xml/System.Numerics.Tensors/TensorPrimitives.xml @@ -3776,7 +3776,7 @@ This computes ( * ) as if to infinite precision, adds to that result as if to - infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence which would compute + infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. @@ -3857,7 +3857,7 @@ This computes ( * ) as if to infinite precision, adds to that result as if to - infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence which would compute + infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. @@ -3937,7 +3937,7 @@ This computes ( * ) as if to infinite precision, adds to that result as if to - infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence which would compute + infinite precision, and finally rounds to the nearest representable value. This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. diff --git a/xml/System.Numerics/BigInteger.xml b/xml/System.Numerics/BigInteger.xml index 5b3e9622a8e..66342fdbb35 100644 --- a/xml/System.Numerics/BigInteger.xml +++ b/xml/System.Numerics/BigInteger.xml @@ -10846,7 +10846,7 @@ The following example calls the The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, throwing an overflow exception for any values that fall outside the representable range of the current type. @@ -10901,7 +10901,7 @@ The following example calls the The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, saturating any values that fall outside the representable range of the current type. @@ -10956,7 +10956,7 @@ The following example calls the The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, truncating any values that fall outside the representable range of the current type. diff --git a/xml/System.Numerics/BitOperations.xml b/xml/System.Numerics/BitOperations.xml index 6c5f3bde870..174aff938b3 100644 --- a/xml/System.Numerics/BitOperations.xml +++ b/xml/System.Numerics/BitOperations.xml @@ -1207,7 +1207,7 @@ If is 0 or the result overflows, returns 0. The value. Rounds the given integral value up to a power of 2. - The smallest power of 2 which is greater than or equal to . + The smallest power of 2 that is greater than or equal to . If is 0 or the result overflows, returns 0. To be added. diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index e307e7112f3..0161b179ee5 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -592,7 +592,7 @@ $(a + c) + bi$ A complex number. Returns the angle that is the arc sine of the specified complex number. - The angle which is the arc sine of . + The angle that is the arc sine of . The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, throwing an overflow exception for any values that fall outside the representable range of the current type. @@ -6426,7 +6426,7 @@ Languages that support custom operators can use the The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, saturating any values that fall outside the representable range of the current type. @@ -6481,7 +6481,7 @@ Languages that support custom operators can use the The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, truncating any values that fall outside the representable range of the current type. diff --git a/xml/System.Numerics/IAdditionOperators`3.xml b/xml/System.Numerics/IAdditionOperators`3.xml index 468f5f77ac6..12ca3cb36fe 100644 --- a/xml/System.Numerics/IAdditionOperators`3.xml +++ b/xml/System.Numerics/IAdditionOperators`3.xml @@ -75,7 +75,7 @@ The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -105,7 +105,7 @@ The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. diff --git a/xml/System.Numerics/IBinaryInteger`1.xml b/xml/System.Numerics/IBinaryInteger`1.xml index 10c2dc002e9..0ea06a7f3d6 100644 --- a/xml/System.Numerics/IBinaryInteger`1.xml +++ b/xml/System.Numerics/IBinaryInteger`1.xml @@ -156,8 +156,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided by . To be added. @@ -506,7 +506,7 @@ - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -536,7 +536,7 @@ - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System.Numerics/IDivisionOperators`3.xml b/xml/System.Numerics/IDivisionOperators`3.xml index 209671a6eea..0a1cc5bc0f0 100644 --- a/xml/System.Numerics/IDivisionOperators`3.xml +++ b/xml/System.Numerics/IDivisionOperators`3.xml @@ -74,8 +74,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided by . To be added. @@ -105,8 +105,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides one value by another to compute their quotient. The quotient of divided by . To be added. diff --git a/xml/System.Numerics/IFloatingPointIeee754`1.xml b/xml/System.Numerics/IFloatingPointIeee754`1.xml index 28130766463..a4a5e415585 100644 --- a/xml/System.Numerics/IFloatingPointIeee754`1.xml +++ b/xml/System.Numerics/IFloatingPointIeee754`1.xml @@ -321,8 +321,8 @@ This computes `arctan(y / x) / π` in the interval `[-1, +1]`. - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . The value that is added to the product of and . Computes the fused multiply-add of three values. The result of times plus computed as one ternary operation. @@ -352,8 +352,8 @@ This computes `arctan(y / x) / π` in the interval `[-1, +1]`. - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the remainder of two values as specified by IEEE 754. The remainder of divided by as specified by IEEE 754. To be added. @@ -593,7 +593,7 @@ This computes `arctan(y / x) / π` in the interval `[-1, +1]`. - The value which base-radix raised to the power of multiplies. + The value that base-radix raised to the power of multiplies. The value to which base-radix is raised before multipliying . Computes the product of a value and its base-radix raised to the specified power. The product of and base-radix raised to the power of . diff --git a/xml/System.Numerics/IModulusOperators`3.xml b/xml/System.Numerics/IModulusOperators`3.xml index 5ce2095c705..b04873a15d1 100644 --- a/xml/System.Numerics/IModulusOperators`3.xml +++ b/xml/System.Numerics/IModulusOperators`3.xml @@ -68,8 +68,8 @@ This type represents the `%` operator in C#, which is often used to compute the - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their modulus or remainder. The modulus or remainder of divided by . To be added. diff --git a/xml/System.Numerics/IMultiplyOperators`3.xml b/xml/System.Numerics/IMultiplyOperators`3.xml index 38f28383557..05eaaa123a7 100644 --- a/xml/System.Numerics/IMultiplyOperators`3.xml +++ b/xml/System.Numerics/IMultiplyOperators`3.xml @@ -74,8 +74,8 @@ - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied by . To be added. @@ -105,8 +105,8 @@ - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied by . To be added. diff --git a/xml/System.Numerics/INumberBase`1.xml b/xml/System.Numerics/INumberBase`1.xml index be4b62c40dc..705217c53a5 100644 --- a/xml/System.Numerics/INumberBase`1.xml +++ b/xml/System.Numerics/INumberBase`1.xml @@ -218,7 +218,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -269,7 +269,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -1472,7 +1472,7 @@ For this method matches the IEE The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert a value to an instance of the the current type, saturating any values that fall outside the representable range of the current type. @@ -1529,7 +1529,7 @@ For this method matches the IEE The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert a value to an instance of the the current type, truncating any values that fall outside the representable range of the current type. @@ -1586,7 +1586,7 @@ For this method matches the IEE The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, throwing an overflow exception for any values that fall outside the representable range of the current type. @@ -1645,7 +1645,7 @@ For this method matches the IEE The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, saturating any values that fall outside the representable range of the current type. @@ -1702,7 +1702,7 @@ For this method matches the IEE The type to which should be converted. - The value which is used to create the instance of . + The value that is used to create the instance of . When this method returns, contains an instance of converted from . Tries to convert an instance of the the current type to another type, truncating any values that fall outside the representable range of the current type. diff --git a/xml/System.Numerics/IPowerFunctions`1.xml b/xml/System.Numerics/IPowerFunctions`1.xml index 0c6fb04ca37..f6b52aff5dd 100644 --- a/xml/System.Numerics/IPowerFunctions`1.xml +++ b/xml/System.Numerics/IPowerFunctions`1.xml @@ -113,7 +113,7 @@ - The value which is raised to the power of . + The value that is raised to the power of . The power to which is raised. Computes a value raised to a given power. diff --git a/xml/System.Numerics/ISignedNumber`1.xml b/xml/System.Numerics/ISignedNumber`1.xml index 20b98d4873f..f488c9c2dad 100644 --- a/xml/System.Numerics/ISignedNumber`1.xml +++ b/xml/System.Numerics/ISignedNumber`1.xml @@ -86,7 +86,7 @@ The type that implements the interface. - Defines a number type which can represent both positive and negative values. + Defines a number type that can represent both positive and negative values. To be added. diff --git a/xml/System.Numerics/ISubtractionOperators`3.xml b/xml/System.Numerics/ISubtractionOperators`3.xml index 9dc93f1ca1a..ebf91c14321 100644 --- a/xml/System.Numerics/ISubtractionOperators`3.xml +++ b/xml/System.Numerics/ISubtractionOperators`3.xml @@ -75,7 +75,7 @@ The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The value of subtracted from . To be added. @@ -106,7 +106,7 @@ The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The value of subtracted from . To be added. diff --git a/xml/System.Numerics/Vector.xml b/xml/System.Numerics/Vector.xml index a14193d43e7..5c02ac9f7a9 100644 --- a/xml/System.Numerics/Vector.xml +++ b/xml/System.Numerics/Vector.xml @@ -3931,7 +3931,7 @@ Note that this method returns a instead of an integral type ( * ) + , rounded as one ternary operation. This computes ( * ) as if to infinite precision, adds to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. @@ -3967,7 +3967,7 @@ Note that this method returns a instead of an integral type ( * ) + , rounded as one ternary operation. This computes ( * ) as if to infinite precision, adds to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index 741eb39b484..163a3c80e71 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -649,7 +649,7 @@ ## Remarks If `fastCopy` is `true`, then the printer must be an [Printing Overview](https://learn.microsoft.com/dotnet/framework/wpf/advanced/printing-overview). If it is not, the method throws an exception. - If `fastCopy` is `false`, then it is not necessary to use an XPSDrv printer. The XPS file being added to the queue is converted to the printer's page description language, such as PCL or Postscript. However, this kind of printing makes a call to Component Object Model (COM). The call to COM requires that the calling thread have a single-threaded apartment () instead of multiple-threaded apartment () which is the default in Microsoft .NET 2.0 and later. (For more on threading and apartment states, see [Managed and Unmanaged Threading](https://msdn.microsoft.com/library/db425c20-4b2f-4433-bf96-76071c7881e5), and .) There are two ways of doing this: + If `fastCopy` is `false`, then it is not necessary to use an XPSDrv printer. The XPS file being added to the queue is converted to the printer's page description language, such as PCL or Postscript. However, this kind of printing makes a call to Component Object Model (COM). The call to COM requires that the calling thread have a single-threaded apartment () instead of multiple-threaded apartment (), which is the default. There are two ways of doing this: - The simplest way is to add the (that is, "`[System.STAThreadAttribute()]`") just above the first line of the application's `Main` method (usually "`static void Main(string[] args)`"). @@ -937,7 +937,7 @@ has no public constructor. Hence, the variable `documentImageableArea` must be declared and assigned to `null` and only then passed to the method. This method displays a requiring input from the user. After the user has selected a printer, paper size, and orientation and closed the dialog, `documentImageableArea` points to an actual object and its properties are initialized. @@ -1080,7 +1080,7 @@ has no public constructor. Hence, the variable `documentImageableArea` must be declared and assigned to `null` and only then passed to the method. This method displays a requiring input from the user. After the user has selected a printer, paper size, and orientation and closed the dialog, `documentImageableArea` points to an actual object, and its properties are initialized. @@ -1138,7 +1138,7 @@ has no public constructor. Hence, the variable `documentImageableArea` must be declared and assigned to `null` and only then passed to the method. This method displays a requiring input from the user. The user configures their print job on the dialog (including selecting a printer, paper size, orientation, and page range). When the dialog is closed, `pageRangeSelection` and `pageRange` have values, and `documentImageableArea` points to an actual object whose properties are initialized. @@ -1194,7 +1194,7 @@ has no public constructor. Hence, the variable `documentImageableArea` must be declared and assigned to `null` and only then passed to the method. This method displays a requiring input from the user. The user configures their print job on the dialog (including selecting a printer, paper size, orientation, and page range). When the dialog is closed, `pageRangeSelection` and `pageRange` have values, and `documentImageableArea` points to an actual object whose properties are initialized. diff --git a/xml/System.Reflection.Emit/DynamicMethod.xml b/xml/System.Reflection.Emit/DynamicMethod.xml index 62e54440840..40153c3ff04 100644 --- a/xml/System.Reflection.Emit/DynamicMethod.xml +++ b/xml/System.Reflection.Emit/DynamicMethod.xml @@ -2443,9 +2443,7 @@ The following code example creates a dynamic method that takes two parameters. T property of a dynamic method. This code example is part of a larger example provided for the class. diff --git a/xml/System.Reflection/AmbiguousMatchException.xml b/xml/System.Reflection/AmbiguousMatchException.xml index 2c510726249..4ee15590a3f 100644 --- a/xml/System.Reflection/AmbiguousMatchException.xml +++ b/xml/System.Reflection/AmbiguousMatchException.xml @@ -82,13 +82,13 @@ The exception that is thrown when binding to a member results in more than one member matching the binding criteria. This class cannot be inherited. - or ). - + or ). + ]]> @@ -148,16 +148,16 @@ Initializes a new instance of the class with an empty message string and the root cause exception set to . - . This constructor sets the properties of the `Exception` object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The empty string ("").| - + . This constructor sets the properties of the `Exception` object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The empty string ("").| + ]]> @@ -210,16 +210,16 @@ A string indicating the reason this exception was thrown. Initializes a new instance of the class with its message string set to the given message and the root cause exception set to . - . This constructor sets the properties of the `Exception` object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The `message` string.| - + . This constructor sets the properties of the `Exception` object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The `message` string.| + ]]> @@ -272,27 +272,27 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - - -## Examples - The following example shows two methods, each named `Mymethod`. One method takes an integer and the other takes a string. If an integer is passed to `Mymethod`, the first method is used. If a string is passed, the second method is used. If it cannot be determined which `Mymethod` to use, `AmbiguousMatchException` is thrown. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + + +## Examples + The following example shows two methods, each named `Mymethod`. One method takes an integer and the other takes a string. If an integer is passed to `Mymethod`, the first method is used. If a string is passed, the second method is used. If it cannot be determined which `Mymethod` to use, `AmbiguousMatchException` is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic AmbiguousMatchException.AmbiguousMatchException2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AmbiguousMatchException/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic AmbiguousMatchException.AmbiguousMatchException2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic AmbiguousMatchException.AmbiguousMatchException2 Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Reflection/AssemblyDelaySignAttribute.xml b/xml/System.Reflection/AssemblyDelaySignAttribute.xml index eb49333ccda..74fc664fd72 100644 --- a/xml/System.Reflection/AssemblyDelaySignAttribute.xml +++ b/xml/System.Reflection/AssemblyDelaySignAttribute.xml @@ -64,28 +64,28 @@ Specifies that the assembly is not fully signed when created. - attribute with the . To compile this example, you must create a strong-name key file named TestPublicKey.snk using the [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool): - -```console -sn -k TestPublicKey.snk -``` - - Compile the example as a .dll. If you compile from the command line, use the `/t:library` option for C# or Visual Basic, or the `/LD` linker option for Visual C++. - + +## Examples + The following code example shows the use of the attribute with the . To compile this example, you must create a strong-name key file named TestPublicKey.snk using the [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool): + +```console +sn -k TestPublicKey.snk +``` + + Compile the example as a .dll. If you compile from the command line, use the `/t:library` option for C# or Visual Basic, or the `/LD` linker option for Visual C++. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyDelaySignAttribute/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyDelaySignAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyDelaySignAttribute/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyDelaySignAttribute/vb/source.vb" id="Snippet1"::: + ]]> Metadata and Self-Describing Components diff --git a/xml/System.Reflection/CustomAttributeFormatException.xml b/xml/System.Reflection/CustomAttributeFormatException.xml index 5407a68df47..bb358983f7c 100644 --- a/xml/System.Reflection/CustomAttributeFormatException.xml +++ b/xml/System.Reflection/CustomAttributeFormatException.xml @@ -59,13 +59,13 @@ The exception that is thrown when the binary format of a custom attribute is invalid. - @@ -118,18 +118,18 @@ Initializes a new instance of the class with the default properties. - |null| -||The empty string ("").| - + |null| +||The empty string ("").| + ]]> @@ -174,15 +174,15 @@ The message that indicates the reason this exception was thrown. Initializes a new instance of the class with the specified message. - |`null`| - + |`null`| + ]]> @@ -288,18 +288,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The `inner` exception.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The `inner` exception.| +||The error message string.| + ]]> diff --git a/xml/System.Reflection/FieldInfo.xml b/xml/System.Reflection/FieldInfo.xml index aa42ae6ee51..6b3e9afcc34 100644 --- a/xml/System.Reflection/FieldInfo.xml +++ b/xml/System.Reflection/FieldInfo.xml @@ -680,7 +680,7 @@ , and which are used to obtain custom modifiers from a function pointer. + A modified type supports , , and , which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . diff --git a/xml/System.Reflection/InvalidFilterCriteriaException.xml b/xml/System.Reflection/InvalidFilterCriteriaException.xml index 2266db76a86..a3b2716479b 100644 --- a/xml/System.Reflection/InvalidFilterCriteriaException.xml +++ b/xml/System.Reflection/InvalidFilterCriteriaException.xml @@ -79,11 +79,11 @@ The exception that is thrown in when the filter criteria is not valid for the type of filter you are using. - @@ -140,18 +140,18 @@ Initializes a new instance of the class with the default properties. - |null| -||The empty string ("").| - + |null| +||The empty string ("").| + ]]> @@ -200,18 +200,18 @@ The message text for the exception. Initializes a new instance of the class with the given HRESULT and message string. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`| +||The error message string.| + ]]> @@ -322,18 +322,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Reflection/ParameterInfo.xml b/xml/System.Reflection/ParameterInfo.xml index 2c76ef2beda..f5e95daeb0f 100644 --- a/xml/System.Reflection/ParameterInfo.xml +++ b/xml/System.Reflection/ParameterInfo.xml @@ -750,7 +750,7 @@ , and which are used to obtain custom modifiers from a function pointer. + A modified type supports , , and , which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . diff --git a/xml/System.Reflection/PropertyInfo.xml b/xml/System.Reflection/PropertyInfo.xml index fef88837481..10de1965426 100644 --- a/xml/System.Reflection/PropertyInfo.xml +++ b/xml/System.Reflection/PropertyInfo.xml @@ -1001,7 +1001,7 @@ , and which are used to obtain custom modifiers from a function pointer. + A modified type supports , , and , which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . diff --git a/xml/System.Reflection/TargetInvocationException.xml b/xml/System.Reflection/TargetInvocationException.xml index 6859281d200..d0116f2210f 100644 --- a/xml/System.Reflection/TargetInvocationException.xml +++ b/xml/System.Reflection/TargetInvocationException.xml @@ -82,15 +82,15 @@ The exception that is thrown by methods invoked through reflection. This class cannot be inherited. - . - - `TargetInvocationException` uses the HRESULT COR_E_TARGETINVOCATION which has the value 0x80131604. - - When created, the `TargetInvocationException` is passed a reference to the exception thrown by the method invoked through reflection. The property holds the underlying exception. - + . + + `TargetInvocationException` uses the HRESULT COR_E_TARGETINVOCATION, which has the value 0x80131604. + + When created, the `TargetInvocationException` is passed a reference to the exception thrown by the method invoked through reflection. The property holds the underlying exception. + ]]> @@ -155,18 +155,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -221,18 +221,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Reflection/TargetParameterCountException.xml b/xml/System.Reflection/TargetParameterCountException.xml index ea146bbfdb5..f9ad3298df3 100644 --- a/xml/System.Reflection/TargetParameterCountException.xml +++ b/xml/System.Reflection/TargetParameterCountException.xml @@ -82,11 +82,11 @@ The exception that is thrown when the number of parameters for an invocation does not match the number expected. This class cannot be inherited. - @@ -145,16 +145,16 @@ Initializes a new instance of the class with an empty message string and the root cause of the exception. - . This constructor sets the properties of the Exception object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The empty string ("").| - + . This constructor sets the properties of the Exception object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The empty string ("").| + ]]> @@ -205,16 +205,16 @@ A describing the reason this exception was thrown. Initializes a new instance of the class with its message string set to the given message and the root cause exception. - . This constructor sets the properties of the `Exception` object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The message string.| - + . This constructor sets the properties of the `Exception` object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The message string.| + ]]> @@ -267,18 +267,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.Caching/ChangeMonitor.xml b/xml/System.Runtime.Caching/ChangeMonitor.xml index 9b5bb88cbdb..25d55c3f075 100644 --- a/xml/System.Runtime.Caching/ChangeMonitor.xml +++ b/xml/System.Runtime.Caching/ChangeMonitor.xml @@ -24,12 +24,12 @@ - Provides a base class for a derived custom type that monitors changes in the state of the data which a cache item depends on. + Provides a base class for a derived custom type that monitors changes in the state of the data that a cache item depends on. class is used as the base class for derived monitor classes that are specialized for particular cache implementations. A instance monitors changes in the state of data which a cache item depends on. For example, the item can be a file or data entity whose contents are cached. If the file or data entity is updated, the associated cache entry must be changed also. Common items that can be monitored include data entities (such as database fields, values, rows, or tables), another cache entry, and files and file attributes. + The class is used as the base class for derived monitor classes that are specialized for particular cache implementations. A instance monitors changes in the state of data that a cache item depends on. For example, the item can be a file or data entity whose contents are cached. If the file or data entity is updated, the associated cache entry must be changed also. Common items that can be monitored include data entities (such as database fields, values, rows, or tables), another cache entry, and files and file attributes. A dependency change is a change in the state of a dependency. In a typical cache implementation, after a instance notifies the cache that a dependency has changed, the cache performs the required action, such as invalidating the inserted cache entry. diff --git a/xml/System.Runtime.CompilerServices/CallSiteBinder.xml b/xml/System.Runtime.CompilerServices/CallSiteBinder.xml index 334aeeb1576..d531ae3dd9d 100644 --- a/xml/System.Runtime.CompilerServices/CallSiteBinder.xml +++ b/xml/System.Runtime.CompilerServices/CallSiteBinder.xml @@ -214,7 +214,7 @@ The CallSite the bind is being performed for. The arguments for the binder. Provides low-level runtime binding support. Classes can override this and provide a direct delegate for the implementation of rule. This can enable saving rules to disk, having specialized rules available at runtime, or providing a different caching policy. - A new delegate which replaces the CallSite Target. + A new delegate that replaces the CallSite Target. To be added. diff --git a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml index cb73eef1d8b..b1b8925d55a 100644 --- a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml +++ b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml @@ -173,7 +173,7 @@ - A bitmask representing the desired value which specifies properties of the attributed method. + A bitmask representing the desired value, which specifies properties of the attributed method. Initializes a new instance of the class with the specified value. To be added. diff --git a/xml/System.Runtime.CompilerServices/StrongBox`1.xml b/xml/System.Runtime.CompilerServices/StrongBox`1.xml index db1c8f424ee..9d81f8cab40 100644 --- a/xml/System.Runtime.CompilerServices/StrongBox`1.xml +++ b/xml/System.Runtime.CompilerServices/StrongBox`1.xml @@ -64,11 +64,11 @@ The type of the value that the references. Holds a reference to a value. - @@ -114,7 +114,7 @@ - Initializes a new StrongBox which can receive a value when used in a reference call. + Initializes a new StrongBox that can receive a value when used in a reference call. To be added. diff --git a/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml b/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml index 189b3393925..258ba537e02 100644 --- a/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml +++ b/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml @@ -133,11 +133,11 @@ The exception that caused the current exception. Initializes an instance of the class by using the error message and the inner exception information passed as parameters. - property. - + property. + ]]> @@ -371,7 +371,7 @@ Gets the GUID associated with the current instance owner (who currently has a lock on the instance). - The GUID associated with the current instance owner. Returns Guid.Empty if the current instance owner is not known. + The GUID associated with the current instance owner. Returns Guid.Empty if the current instance owner is not known. To be added. @@ -397,7 +397,7 @@ System.Collections.Generic.IDictionary<System.Xml.Linq.XName,System.Object> - Gets serializable metadata information about the current instance owner (who currently has a lock on the instance). When present, this consists of the subset of instance owner metadata which is serializable. The metadata may contain information such as the location of the instance owner, who currently owns the lock. + Gets serializable metadata information about the current instance owner (who currently has a lock on the instance). When present, this consists of the subset of instance owner metadata that is serializable. The metadata may contain information such as the location of the instance owner, who currently owns the lock. The serializable metadata information about the current instance owner (who currently has a lock on the instance). To be added. diff --git a/xml/System.Runtime.DurableInstancing/InstancePersistenceContext.xml b/xml/System.Runtime.DurableInstancing/InstancePersistenceContext.xml index 25a3fde7341..2eb307ab602 100644 --- a/xml/System.Runtime.DurableInstancing/InstancePersistenceContext.xml +++ b/xml/System.Runtime.DurableInstancing/InstancePersistenceContext.xml @@ -16,11 +16,11 @@ Represents execution state information while a persistence command is being executed. - @@ -47,11 +47,11 @@ The instance key identifier for the key that has been associated. Must not be Guid.Empty. Indicates that the persistence provider has successfully associated a key to the current instance in the instance store. The identifier of the key is specified as a parameter. - @@ -85,15 +85,15 @@ Begin an asynchronous operation to bind an existing lock on an instance to the current instance handle. The version of the existing lock is passed as a parameter. The status of an asynchronous operation. - @@ -127,11 +127,11 @@ Begins executing a persistence command asynchronously. The status of an asynchronous operation. - @@ -158,13 +158,13 @@ Version of the lock acquired on the instance, or zero if the persistence provider does not implement lock versions. Binds a newly acquired lock on an instance to the current instance handle. The version of the acquired lock is passed as a parameter. - @@ -215,11 +215,11 @@ An instance identifier. Must not be Guid.Empty. Binds an instance whose identifier is specified as a parameter to the current instance handle. - @@ -248,11 +248,11 @@ The lock token of the instance owner. A persistence provider may choose to use the same value for the instance owner identifier and the owner's lock token. Binds an instance owner to the current instance handle. - @@ -281,15 +281,15 @@ The time-out value for the operation. Binds an existing lock on an instance to the current instance handle. The version of the existing lock is passed as a parameter. - @@ -313,11 +313,11 @@ Indicates that the persistence provider has successfully marked the current instance as complete in the instance store. - @@ -344,11 +344,11 @@ The instance key identifier for the key that has been completed. Must not be Guid.Empty. Indicates that the persistence provider has successfully marked a key as complete in the external store. The identifier of the key is specified as a parameter. - @@ -376,26 +376,26 @@ Creates an instance of an exception which can be thrown from TryCommand to trigger BindReclaimedLock behavior. An exception. - @@ -472,11 +472,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The time-out value for the operation. Executes a persistence command. - @@ -527,11 +527,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP Gets the version of the lock held on the current instance by the current instance handle. The version of the instance lock bound to the current instance handle, or -1 if the handle isn't bound to a lock. - @@ -593,11 +593,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP Completed instance metadata as a dictionary of instance identifier and instance key metadata, which is a dictionary of and objects. Indicates that the persistence provider has successfully retrieved the current instance from the instance store. - @@ -621,13 +621,13 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP Gets the lock token of the instance owner bound to the current instance handle. The lock token bound to the current instance handle, or if the handle isn't bound to an instance owner. - @@ -654,11 +654,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP Instance data as a dictionary of and objects. Indicates that the persistence provider has successfully persisted a set of instance data to the instance store. This has the effect of initializing the instance if it wasn't already. - @@ -714,11 +714,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP if the metadata represents all of the metadata associated to the instance key; otherwise, . Indicates that the persistence provider has successfully read some instance key metadata for a key associated to the current instance from the instance store. - @@ -774,11 +774,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The value to specify whether the consistency to be set to or . Sets the instance owner metadata using the data passed in the parameter. - @@ -805,11 +805,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The reference to a function to be called. Sets the cancellation handler to be called when the cancel of an operation is requested. - @@ -836,11 +836,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The instance key identifier for the key that has been unassociated. Must not be Guid.Empty. Indicates that the persistence provider has successfully disassociated a key from the current instance in the instance store. The identifier of the key is specified as a parameter. - @@ -864,11 +864,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP Gets the user context information attached to the current instance handle. The user context information. - @@ -899,11 +899,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The value of the metadata property. Indicates that the persistence provider has successfully written a metadata value for an instance key that is associated with the current instance to the instance store. - @@ -932,11 +932,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The value of the metadata property. Indicates that the persistence provider has successfully written a metadata value for the current instance to the external instance store. - @@ -965,11 +965,11 @@ protected override bool TryCommand(InstancePersistenceContext context, InstanceP The value of the metadata property. Indicates that the persistence provider has successfully written a metadata value for the current instance owner to the instance store. - diff --git a/xml/System.Runtime.InteropServices.ComTypes/ITypeInfo2.xml b/xml/System.Runtime.InteropServices.ComTypes/ITypeInfo2.xml index 550c130233a..3259709d496 100644 --- a/xml/System.Runtime.InteropServices.ComTypes/ITypeInfo2.xml +++ b/xml/System.Runtime.InteropServices.ComTypes/ITypeInfo2.xml @@ -66,11 +66,11 @@ Provides the managed definition of the interface. - @@ -128,11 +128,11 @@ When this method returns, contains a reference to the member. This parameter is passed uninitialized. Retrieves the addresses of static functions or variables, such as those defined in a DLL. - @@ -199,11 +199,11 @@ When this method returns, contains a reference to the created object. This parameter is passed uninitialized. Creates a new instance of a type that describes a component class (coclass). - @@ -304,11 +304,11 @@ A pointer to , which holds all custom data items. Gets all custom data from the specified function. - @@ -358,14 +358,14 @@ The index of the implementation type for the custom data. - A pointer to which holds all custom data items. + A pointer to that holds all custom data items. Gets all custom data for the specified implementation type. - @@ -523,11 +523,11 @@ When this method returns, contains a reference to the index of the type description within the containing type library. This parameter is passed uninitialized. Retrieves the type library that contains this type description and its index within that type library. - @@ -580,11 +580,11 @@ When this method returns, contains an that specifies where to put the retrieved data. This parameter is passed uninitialized. Gets the custom data. - @@ -646,11 +646,11 @@ If not , and the function is defined by an ordinal, then lpwOrdinal is set to point to the ordinal. Retrieves a description or specification of an entry point for a function in a DLL. - @@ -712,11 +712,11 @@ When this method returns, contains the fully qualified name of the Help file. This parameter is passed uninitialized. Retrieves the documentation string, the complete Help file name and path, and the context ID for the Help topic for a specified type description. - @@ -884,13 +884,13 @@ When this method returns, contains a reference to a structure that describes the specified function. This parameter is passed uninitialized. Retrieves the structure that contains information about a specified function. - method. - + method. + For more information, see [ITypeInfo::GetFuncDesc method](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getfuncdesc). - + ]]> @@ -1001,11 +1001,11 @@ When this method returns, contains a reference to an array in which name mappings are placed. This parameter is passed uninitialized. Maps between member names and member IDs, and parameter names and parameter IDs. - @@ -1060,11 +1060,11 @@ When this method returns, contains an that specifies where to put the retrieved data. This parameter is passed uninitialized. Gets the implementation type of the custom data. - @@ -1120,11 +1120,11 @@ When this method returns, contains a reference to the enumeration. This parameter is passed uninitialized. Retrieves the value for one implemented interface or base interface in a type description. - @@ -1181,11 +1181,11 @@ When this method returns, contains a reference to the string used in marshaling the fields of the structure described by the referenced type description, or returns if there is no information to return. This parameter is passed uninitialized. Retrieves marshaling information. - @@ -1246,11 +1246,11 @@ When this method returns, contains the number of names in the array. This parameter is passed uninitialized. Retrieves the variable with the specified member ID (or the name of the property or method and its parameters) that corresponds to the specified function ID. - @@ -1360,11 +1360,11 @@ When this method returns, contains the referenced type description. This parameter is passed uninitialized. Retrieves the referenced type descriptions, if a type description references other type descriptions. - @@ -1420,11 +1420,11 @@ When this method returns, contains a reference to a handle for the implemented interface. This parameter is passed uninitialized. Retrieves the type description of the implemented interface types, if a type description describes a COM class. - @@ -1478,13 +1478,13 @@ When this method returns, contains a reference to the structure that contains the attributes of this type description. This parameter is passed uninitialized. Retrieves a structure that contains the attributes of the type description. - method. - + method. + For more information, see [ITypeInfo::GetTypeAttr method](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-gettypeattr). - + ]]> @@ -1538,11 +1538,11 @@ When this method returns, contains a reference to the of the containing type library. This parameter is passed uninitialized. Retrieves the interface for the type description, which enables a client compiler to bind to the type description's members. - @@ -1693,11 +1693,11 @@ When this method returns, contains an that specifies where to put the retrieved data. This parameter is passed uninitialized. Gets the variable for the custom data. - @@ -1753,13 +1753,13 @@ When this method returns, contains a reference to the structure that describes the specified variable. This parameter is passed uninitialized. Retrieves a structure that describes the specified variable. - method. - + method. + For more information, see [ITypeInfo::GetVarDesc method](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getvardesc). - + ]]> @@ -1875,22 +1875,22 @@ If returns , indicates the index of the argument with incorrect type. If more than one argument returns an error, indicates only the first argument with an error. Invokes a method, or accesses a property of an object, that implements the interface described by the type description. - method. - - Valid values for `wFlags` are: - -|Value|Description| -|-----------|-----------------| -|DISPATCH_METHOD|The member is accessed as a method. If there is ambiguity, both this flag and the `DISPATCH_PROPERTYGET` flag can be set.| -|DISPATCH_PROPERTYGET|The member is retrieved as a property or data member.| -|DISPATCH_PROPERTYPUT|The member is changed as a property or data member.| -|DISPATCH_PROPERTYPUTREF|The member is changed by using a reference assignment, rather than a value assignment. This value is valid only when the property accepts a reference to an object.| - + method. + + Valid values for `wFlags` are: + +|Value|Description| +|-----------|-----------------| +|DISPATCH_METHOD|The member is accessed as a method. If there is ambiguity, both this flag and the `DISPATCH_PROPERTYGET` flag can be set.| +|DISPATCH_PROPERTYGET|The member is retrieved as a property or data member.| +|DISPATCH_PROPERTYPUT|The member is changed as a property or data member.| +|DISPATCH_PROPERTYPUTREF|The member is changed by using a reference assignment, rather than a value assignment. This value is valid only when the property accepts a reference to an object.| + For more information, see [ITypeInfo::Invoke method](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-invoke). - + ]]> @@ -1944,11 +1944,11 @@ A reference to the structure to release. Releases a structure previously returned by the method. - @@ -2002,11 +2002,11 @@ A reference to the structure to release. Releases a structure previously returned by the method. - @@ -2060,11 +2060,11 @@ A reference to the structure to release. Releases a structure previously returned by the method. - diff --git a/xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument.xml b/xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument.xml index e79c4cc9f78..bd983a2d56d 100644 --- a/xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument.xml +++ b/xml/System.Runtime.InteropServices.JavaScript/JSMarshalerArgument.xml @@ -1253,7 +1253,7 @@ The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1301,7 +1301,7 @@ The type of marshalled result of the . The value to be marshalled. - The generated callback which marshals the result value of the . + The generated callback that marshals the result value of the . Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1349,7 +1349,7 @@ The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the result of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1407,8 +1407,8 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1466,8 +1466,8 @@ The type of the marshalled argument of the Action. The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1535,9 +1535,9 @@ The type of the marshalled argument of the Action. The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1605,9 +1605,9 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -1685,10 +1685,10 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -2939,7 +2939,7 @@ The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -2987,7 +2987,7 @@ The type of marshalled result of the . The value to be marshalled. - The generated callback which marshals the result value of the . + The generated callback that marshals the result value of the . Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3035,7 +3035,7 @@ The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the result of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3093,8 +3093,8 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3152,8 +3152,8 @@ The type of the marshalled argument of the Action. The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3221,9 +3221,9 @@ The type of the marshalled argument of the Action. The type of the marshalled argument of the Action. The value to be marshalled. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. - The generated callback which marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. + The generated callback that marshals the argument of the Action. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3291,9 +3291,9 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. @@ -3371,10 +3371,10 @@ The type of the marshalled argument of the Func. The type of marshalled result of the Func. The value to be marshalled. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the argument of the Func. - The generated callback which marshals the result of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the argument of the Func. + The generated callback that marshals the result of the Func. Marshals the specified value. This API supports JSImport infrastructure and is not intended to be used directly from your code. To be added. diff --git a/xml/System.Runtime.InteropServices/ExternalException.xml b/xml/System.Runtime.InteropServices/ExternalException.xml index 7226447b343..b8387f86d85 100644 --- a/xml/System.Runtime.InteropServices/ExternalException.xml +++ b/xml/System.Runtime.InteropServices/ExternalException.xml @@ -59,17 +59,17 @@ The base exception type for all COM interop exceptions and structured exception handling (SEH) exceptions. - property stores an integer value (HRESULT) that identifies the error. User defined exceptions should never derive from `ExternalException`, and an `ExternalException` should never be thrown by user code. Use the specific exceptions that derive from `ExternalException` instead. - - `ExternalException` uses the HRESULT E_FAIL which has the value 0x80004005. - - `ExternalException` uses the default implementation, which supports reference equality. - - For a list of initial values for an instance of `ExternalException`, see the `ExternalException` constructors. - + property stores an integer value (HRESULT) that identifies the error. User defined exceptions should never derive from `ExternalException`, and an `ExternalException` should never be thrown by user code. Use the specific exceptions that derive from `ExternalException` instead. + + `ExternalException` uses the HRESULT E_FAIL, which has the value 0x80004005. + + `ExternalException` uses the default implementation, which supports reference equality. + + For a list of initial values for an instance of `ExternalException`, see the `ExternalException` constructors. + ]]> @@ -121,16 +121,16 @@ Initializes a new instance of the class with default properties. - |A null reference (`Nothing` in Visual Basic).| -||A localized error message string.| - + |A null reference (`Nothing` in Visual Basic).| +||A localized error message string.| + ]]> @@ -175,16 +175,16 @@ The error message that specifies the reason for the exception. Initializes a new instance of the class with a specified error message. - |A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + |A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -244,11 +244,11 @@ The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - @@ -297,18 +297,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -357,17 +357,17 @@ The HRESULT of the error. Initializes a new instance of the class with a specified error message and the HRESULT of the error. - |The HRESULT of the error.| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + |The HRESULT of the error.| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -411,11 +411,11 @@ Gets the of the error. The of the error. - diff --git a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml index 68f06d8b7c0..64daed5fbba 100644 --- a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml +++ b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml @@ -77,7 +77,7 @@ ## Remarks An `InvalidComObjectException` is thrown when an invalid COM object is used. This happens when the `__ComObject` type is used directly, without having a backing class factory. For more information, see . - `InvalidComObjectException` uses the HRESULT COR_E_INVALIDCOMOBJECT which has the value 0x80131527. + `InvalidComObjectException` uses the HRESULT COR_E_INVALIDCOMOBJECT, which has the value 0x80131527. ]]> diff --git a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml index c08ddcc56c6..277365e1c7e 100644 --- a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml +++ b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml @@ -75,7 +75,7 @@ diff --git a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml index a067231abb6..98e58118d9e 100644 --- a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml +++ b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml @@ -75,7 +75,7 @@ diff --git a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml index e7c9748f4b2..f723cc62cba 100644 --- a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml +++ b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml @@ -75,7 +75,7 @@ diff --git a/xml/System.Runtime.InteropServices/UCOMIStream.xml b/xml/System.Runtime.InteropServices/UCOMIStream.xml index d5730dc8ba2..0d8ece987ea 100644 --- a/xml/System.Runtime.InteropServices/UCOMIStream.xml +++ b/xml/System.Runtime.InteropServices/UCOMIStream.xml @@ -30,11 +30,11 @@ Use instead. - @@ -63,11 +63,11 @@ On successful return, contains the new stream object. Creates a new stream object with its own seek pointer that references the same bytes as the original stream. - @@ -96,11 +96,11 @@ Controls how the changes for the stream object are committed. Ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. - @@ -135,11 +135,11 @@ On successful return, contains the actual number of bytes written to the destination. Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream. - @@ -172,11 +172,11 @@ The requested restrictions on accessing the range. Restricts access to a specified range of bytes in the stream. - @@ -209,11 +209,11 @@ Pointer to a variable that receives the actual number of bytes read from the stream object. Reads a specified number of bytes from the stream object into memory starting at the current seek pointer. - @@ -239,11 +239,11 @@ Discards all changes that have been made to a transacted stream since the last call. - @@ -276,11 +276,11 @@ On successful return, contains the offset of the seek pointer from the beginning of the stream. Changes the seek pointer to a new location relative to the beginning of the stream, to the end of the stream, or to the current seek pointer. - @@ -309,11 +309,11 @@ Specifies the new size of the stream as a number of bytes. Changes the size of the stream object. - @@ -340,15 +340,15 @@ - On successful return, contains a structure which describes this stream object. + On successful return, contains a structure that describes this stream object. Specifies some of the members in the structure that this method does not return, thus saving some memory allocation operations. Retrieves the structure for this stream. - @@ -381,11 +381,11 @@ The access restrictions previously placed on the range. Removes the access restriction on a range of bytes previously restricted with . - @@ -418,11 +418,11 @@ On successful return, contains the actual number of bytes written to the stream object. The caller can set this pointer to , in which case this method does not provide the actual number of bytes written. Writes a specified number of bytes into the stream object starting at the current seek pointer. - diff --git a/xml/System.Runtime.Intrinsics/Vector128.xml b/xml/System.Runtime.Intrinsics/Vector128.xml index cb689d58c8a..5d0bc0e0da1 100644 --- a/xml/System.Runtime.Intrinsics/Vector128.xml +++ b/xml/System.Runtime.Intrinsics/Vector128.xml @@ -2437,7 +2437,7 @@ The type of the elements in the vector. The vector to be copied. The array to which is copied. - The starting index of which will be copied to. + The starting index of to which will be copied. Copies a to a given array starting at the specified index. To be added. The length of is less than . diff --git a/xml/System.Runtime.Intrinsics/Vector256.xml b/xml/System.Runtime.Intrinsics/Vector256.xml index 4c81b39f5ad..b2c688e632a 100644 --- a/xml/System.Runtime.Intrinsics/Vector256.xml +++ b/xml/System.Runtime.Intrinsics/Vector256.xml @@ -2199,7 +2199,7 @@ The type of the elements in the vector. The vector to be copied. The array to which is copied. - The starting index of which will be copied to. + The starting index of to which will be copied. Copies a to a given array starting at the specified index. To be added. The length of is less than . diff --git a/xml/System.Runtime.Intrinsics/Vector512.xml b/xml/System.Runtime.Intrinsics/Vector512.xml index 723ad31d581..ac8864951b1 100644 --- a/xml/System.Runtime.Intrinsics/Vector512.xml +++ b/xml/System.Runtime.Intrinsics/Vector512.xml @@ -1970,7 +1970,7 @@ The type of the elements in the vector. The vector to be copied. The array to which is copied. - The starting index of which will be copied to. + The starting index of to which will be copied. Copies a to a given array starting at the specified index. To be added. The length of is less than . diff --git a/xml/System.Runtime.Intrinsics/Vector64.xml b/xml/System.Runtime.Intrinsics/Vector64.xml index 559dc771b09..04aef99fe1f 100644 --- a/xml/System.Runtime.Intrinsics/Vector64.xml +++ b/xml/System.Runtime.Intrinsics/Vector64.xml @@ -2091,7 +2091,7 @@ The type of the elements in the vector. The vector to be copied. The array to which is copied. - The starting index of which will be copied to. + The starting index of to which will be copied. Copies a to a given array starting at the specified index. To be added. The length of is less than . @@ -4749,7 +4749,7 @@ On x86, this method corresponds to __m64 _mm_setr_pi8 ( * ) + , rounded as one ternary operation. This computes ( * ) as if to infinite precision, adds to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. @@ -4782,7 +4782,7 @@ On x86, this method corresponds to __m64 _mm_setr_pi8 ( * ) + , rounded as one ternary operation. This computes ( * ) as if to infinite precision, adds to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, would compute ( * ) as if to infinite precision, round the result to the nearest representable value, add to the rounded result as if to infinite precision, and finally round to the nearest representable value. diff --git a/xml/System.Runtime.Loader/AssemblyLoadContext+ContextualReflectionScope.xml b/xml/System.Runtime.Loader/AssemblyLoadContext+ContextualReflectionScope.xml index 24a89c54242..5e23e20601c 100644 --- a/xml/System.Runtime.Loader/AssemblyLoadContext+ContextualReflectionScope.xml +++ b/xml/System.Runtime.Loader/AssemblyLoadContext+ContextualReflectionScope.xml @@ -37,7 +37,7 @@ ### Remarks -This is an implementation detail of the APIs. It is a struct, to avoid heap allocation. It is required to be public to avoid boxing. +This is an implementation detail of the APIs. It is a struct, to avoid heap allocation. It is required to be public to avoid boxing. ]]> @@ -70,7 +70,7 @@ This is an implementation detail of the - Sets to the value preceding the call to which returned this instance. + Sets to the value preceding the call to that returned this instance. To be added. diff --git a/xml/System.Runtime.Loader/AssemblyLoadContext.xml b/xml/System.Runtime.Loader/AssemblyLoadContext.xml index c848b271fc0..a716c585432 100644 --- a/xml/System.Runtime.Loader/AssemblyLoadContext.xml +++ b/xml/System.Runtime.Loader/AssemblyLoadContext.xml @@ -347,7 +347,7 @@ For more information, see [AssemblyLoadContext.CurrentContextualReflectionContex The assembly that is used to determine the requested instance. - Sets to the which loaded the assembly. + Sets to the that loaded the assembly. An object to restore the previous value of . It is intended to be used as an in a block. can load only: is not found. is not a valid assembly. - An assembly or module was loaded which did not match the . + An assembly or module was loaded that did not match the . Managed assembly loading algorithm diff --git a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml index db9f70e4ac0..42eac0a56ce 100644 --- a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml +++ b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml @@ -32,29 +32,29 @@ Encapsulates the results of an asynchronous operation on a delegate. - class is used in conjunction with asynchronous method calls made using delegates. The returned from the delegate's `BeginInvoke` method can be cast to an . The has the property that holds the delegate object on which the asynchronous call was invoked. - - For more information about `BeginInvoke` and asynchronous calls using delegates, see [Asynchronous Programming Using Delegates](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates). - - - -## Examples - The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. - - The example consists of two classes, the class that contains the method which is called asynchronously, and the class that contains the `Main` method that makes the call. - - For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - + class is used in conjunction with asynchronous method calls made using delegates. The returned from the delegate's `BeginInvoke` method can be cast to an . The has the property that holds the delegate object on which the asynchronous call was invoked. + + For more information about `BeginInvoke` and asynchronous calls using delegates, see [Asynchronous Programming Using Delegates](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates). + + + +## Examples + The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. + + The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. + + For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/TestMethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/TestMethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/waithandle.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/waithandle.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/WaitHandle.vb" id="Snippet3"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/WaitHandle.vb" id="Snippet3"::: + ]]> Asynchronous Programming Using Delegates @@ -81,29 +81,29 @@ Gets the delegate object on which the asynchronous call was invoked. The delegate object on which the asynchronous call was invoked. - property can be cast to the actual class of the user-defined delegate. - - For example, if the delegate that was used to make the asynchronous call is of type `MyDelegate`, the delegate that is returned by this property must be cast to `MyDelegate`. The callback method can then call the delegate's `EndInvoke` method with the correct signature, in order to obtain the results of the asynchronous method call. - - - -## Examples - The following code example demonstrates how to use the property to get the delegate that was used to make the asynchronous call, in order to call `EndInvoke`. The example casts the , which is the only parameter of the callback method, to an object. - - The example consists of two classes, the class that contains the method which is called asynchronously, and the class that contains the `Main` method that makes the call. - - For more information on the way this callback example works, and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - + property can be cast to the actual class of the user-defined delegate. + + For example, if the delegate that was used to make the asynchronous call is of type `MyDelegate`, the delegate that is returned by this property must be cast to `MyDelegate`. The callback method can then call the delegate's `EndInvoke` method with the correct signature, in order to obtain the results of the asynchronous method call. + + + +## Examples + The following code example demonstrates how to use the property to get the delegate that was used to make the asynchronous call, in order to call `EndInvoke`. The example casts the , which is the only parameter of the callback method, to an object. + + The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. + + For more information on the way this callback example works, and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/TestMethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/TestMethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/callback.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/callback.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/callback.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/callback.vb" id="Snippet5"::: + ]]> @@ -144,11 +144,11 @@ Implements the interface. No value is returned. - method of the interface is not relevant to the class. Implementation by throws a . Instead, obtain an by casting the interface returned by an asynchronous call made using a delegate. - + method of the interface is not relevant to the class. Implementation by throws a . Instead, obtain an by casting the interface returned by an asynchronous call made using a delegate. + ]]> @@ -177,27 +177,27 @@ Gets the object provided as the last parameter of a method call. The object provided as the last parameter of a method call. - property is used to pass information to a callback method. The last parameter of the `BeginInvoke` method call is a format string, which the callback method uses to format an output message. - - The example consists of two classes, the class that contains the method which is called asynchronously, and the class that contains the `Main` method that makes the call. - - For more information on the way this callback example works, and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - + property is used to pass information to a callback method. The last parameter of the `BeginInvoke` method call is a format string, which the callback method uses to format an output message. + + The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. + + For more information on the way this callback example works, and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/TestMethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/TestMethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/callback.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/callback.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/callback.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/callback.vb" id="Snippet5"::: + ]]> @@ -226,32 +226,32 @@ Gets a that encapsulates Win32 synchronization handles, and allows the implementation of various synchronization schemes. A that encapsulates Win32 synchronization handles, and allows the implementation of various synchronization schemes. - returned by this method is automatically signaled when the asynchronous operation has completed. - - The wait handle is not closed automatically when you call `EndInvoke` on the delegate that was used to make the asynchronous method call. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, call the method. Garbage collection works more efficiently when disposable objects are explicitly closed or disposed. - + returned by this method is automatically signaled when the asynchronous operation has completed. + + The wait handle is not closed automatically when you call `EndInvoke` on the delegate that was used to make the asynchronous method call. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, call the method. Garbage collection works more efficiently when disposable objects are explicitly closed or disposed. + > [!CAUTION] -> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. - - - -## Examples - The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. - - The example consists of two classes, the class that contains the method which is called asynchronously, and the class that contains the `Main` method that makes the call. - - For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - +> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. + + + +## Examples + The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. + + The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. + + For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/TestMethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/TestMethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/waithandle.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/waithandle.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/WaitHandle.vb" id="Snippet3"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/WaitHandle.vb" id="Snippet3"::: + ]]> @@ -282,13 +282,13 @@ if the call completed synchronously; otherwise, . - delegate, it is probable that the thread that called BeginInvoke is the current thread. Most providers of the interface will not use the capability and will return a default `false`. - - Current implementation of always returns `false`. - + delegate, it is probable that the thread that called BeginInvoke is the current thread. Most providers of the interface will not use the capability and will return a default `false`. + + Current implementation of always returns `false`. + ]]> @@ -339,13 +339,13 @@ Gets the response message for the asynchronous call. A remoting message that should represent a response to a method call on a remote object. - method can return an object after the method is called. The return value can be cast to an . - - However, you do not need to call either of these methods directly. They are intended for use by the remoting infrastructure of the .NET Framework. - + method can return an object after the method is called. The return value can be cast to an . + + However, you do not need to call either of these methods directly. They are intended for use by the remoting infrastructure of the .NET Framework. + ]]> @@ -375,27 +375,27 @@ after the server has completed the call; otherwise, . - property to `true`. Thus, it is safe for the client to destroy the resources after the property returns `true`. - - - -## Examples - The following example shows how to use the property of the returned by `BeginInvoke` to discover when an asynchronous call completes. You might do this when making the asynchronous call from a thread that services the user interface. Polling for completion allows the calling thread to continue executing while the asynchronous call executes on a thread. - - The example consists of two classes, the class that contains the method which is called asynchronously, and the class that contains the `Main` method that makes the call. - - For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - + property to `true`. Thus, it is safe for the client to destroy the resources after the property returns `true`. + + + +## Examples + The following example shows how to use the property of the returned by `BeginInvoke` to discover when an asynchronous call completes. You might do this when making the asynchronous call from a thread that services the user interface. Polling for completion allows the calling thread to continue executing while the asynchronous call executes on a thread. + + The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. + + For more information and more examples of calling methods asynchronously by using delegates, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/TestMethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/TestMethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/TestMethod.vb" id="Snippet1"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/polling.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System/IAsyncResult/Overview/polling.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/polling.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/polling.vb" id="Snippet4"::: + ]]> @@ -430,11 +430,11 @@ Gets the next message sink in the sink chain. An interface that represents the next message sink in the sink chain. - returns `null`. - + returns `null`. + ]]> @@ -463,11 +463,11 @@ The for the current remote method call. Sets an for the current remote method call, which provides a way to control asynchronous messages after they have been dispatched. - method. - + method. + ]]> @@ -506,15 +506,15 @@ Synchronously processes a response message returned by a method call on a remote object. Returns . - method implements the interface. You do not need to call this method directly. It is intended for use by the remoting infrastructure of the .NET Framework. - - invokes the consumer code's delegate. It also sets the instance returned by the method. If the `msg` parameter is of type , the same object is returned by . Otherwise, a reply message that contains a remoting exception is returned. - - also modifies the value returned by the property. - + method implements the interface. You do not need to call this method directly. It is intended for use by the remoting infrastructure of the .NET Framework. + + invokes the consumer code's delegate. It also sets the instance returned by the method. If the `msg` parameter is of type , the same object is returned by . Otherwise, a reply message that contains a remoting exception is returned. + + also modifies the value returned by the property. + ]]> diff --git a/xml/System.Runtime.Serialization/ISafeSerializationData.xml b/xml/System.Runtime.Serialization/ISafeSerializationData.xml index e9db78a7571..28c5900c889 100644 --- a/xml/System.Runtime.Serialization/ISafeSerializationData.xml +++ b/xml/System.Runtime.Serialization/ISafeSerializationData.xml @@ -46,13 +46,13 @@ Enables serialization of custom exception data in security-transparent code. - method. Starting with .NET Framework 4.0, that method is marked with the attribute which prevents execution in security-transparent code. To work around this condition, implement the interface and add custom data as shown in the example below. - + method. Starting with .NET Framework 4.0, that method is marked with the attribute, which prevents execution in security-transparent code. To work around this condition, implement the interface and add custom data as shown in the example below. + The method is called after serialization, and uses the to restore the custom data. - + ]]> @@ -98,11 +98,11 @@ An object that contains the state of the instance. This method is called when the instance is deserialized. - class. - + ]]> diff --git a/xml/System.Security.Claims/Claim.xml b/xml/System.Security.Claims/Claim.xml index e00267dc494..bf1e4051251 100644 --- a/xml/System.Security.Claims/Claim.xml +++ b/xml/System.Security.Claims/Claim.xml @@ -57,41 +57,41 @@ class.) On occasion, the collection of claims received from an issuer can be extended by subject attributes stored directly at the resource. A claim can be evaluated to determine access rights to data and other secured resources during the process of authorization and can also be used to make or express authentication decisions about a subject. - - Beginning with .NET 4.5, the Windows Identity Foundation (WIF) classes, which implement claims-based identity, have been fully integrated into the .NET Framework. The claims concept is implemented by the class. - - The following describes important properties of the class: - -- The property is a string (typically a URI) that contains the semantic information about the claim; it tells you what the value of the claim means. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The value of the property can be one of the well-known claim types defined in the class, or it can be an arbitrary URI as defined by the issuer. For example, a claim type of "urn:spendinglimit" might represent a user attribute which makes sense within the business context of the issuer. - -- The property contains the value of the claim. In order to reduce dependencies and simplify administration, in WIF the value of a claim is represented only as a string. For more complex value types, it is recommended that you use standard XML schema types to indicate how the value is meant to be serialized into and deserialized from a string. - -- The property contains a string that identifies the type information for the value. This property should be used to understand the format of the value and to provide information about how to deserialize it. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized into and deserialized from a string. - -- The property is a object that represents the subject of the claim. The subject of the claim is the entity (typically the user who is requesting access to a resource) about which the claim is asserted. The contains, among its properties, a collection of claims that describe the properties and attributes of the subject as attested to by one or more issuers. - -- The property contains the name of the entity that issued the claim. The issuer of a claim is represented in WIF by a string that contains a name taken from a list of well-known issuers that is maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name to the cryptographic material needed to verify the signatures of tokens produced by the corresponding issuer. For example, the class, available out of the box with .NET 4.5, associates the mnemonic name for each issuer with its corresponding X.509 certificate. The list of well-known issuers is typically built at startup time by the issuer name registry. The list used by the is specified in the application configuration file. - -- The property contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. You can examine the property to determine the entity that originally issued the claim. The name is taken from the list of well-known issuers maintained by the issuer name registry, as in the case of the property. - - - -## Examples - The following example extracts the claims associated to the authenticated user performing an HTTP request and writes them in the HTTP response. The current user is read from the as a and the claims are read from it. The claims are then written to the object. - -```csharp -ClaimsPrincipal principal = HttpContext.Current.User as ClaimsPrincipal; -if (null != principal) -{ - foreach (Claim claim in principal.Claims) - { - Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "
"); - } - -} - +## Remarks + A claim is a statement about a subject by an issuer. Claims represent attributes of the subject that are useful in the context of authentication and authorization operations. Subjects and issuers are both entities that are part of an identity scenario. Some typical examples of a subject are: a user, an application or service, a device, or a computer. Some typical examples of an issuer are: the operating system, an application, a service, a role provider, an identity provider, or a federation provider. An issuer delivers claims by issuing security tokens, typically through a Security Token Service (STS). On occasion, the collection of claims received from an issuer can be extended by subject attributes stored directly at the resource. A claim can be evaluated to determine access rights to data and other secured resources during the process of authorization and can also be used to make or express authentication decisions about a subject. + + Beginning with .NET Framework 4.5, the Windows Identity Foundation (WIF) classes, which implement claims-based identity, have been fully integrated into .NET Framework. The claims concept is implemented by the class. + + The following describes important properties of the class: + +- The property is a string (typically a URI) that contains the semantic information about the claim; it tells you what the value of the claim means. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The value of the property can be one of the well-known claim types defined in the class, or it can be an arbitrary URI as defined by the issuer. For example, a claim type of "urn:spendinglimit" might represent a user attribute that makes sense within the business context of the issuer. + +- The property contains the value of the claim. In order to reduce dependencies and simplify administration, in WIF the value of a claim is represented only as a string. For more complex value types, it is recommended that you use standard XML schema types to indicate how the value is meant to be serialized into and deserialized from a string. + +- The property contains a string that identifies the type information for the value. This property should be used to understand the format of the value and to provide information about how to deserialize it. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized into and deserialized from a string. + +- The property is a object that represents the subject of the claim. The subject of the claim is the entity (typically the user who is requesting access to a resource) about which the claim is asserted. The contains, among its properties, a collection of claims that describe the properties and attributes of the subject as attested to by one or more issuers. + +- The property contains the name of the entity that issued the claim. The issuer of a claim is represented in WIF by a string that contains a name taken from a list of well-known issuers that is maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name to the cryptographic material needed to verify the signatures of tokens produced by the corresponding issuer. For example, the class, available out of the box with .NET 4.5, associates the mnemonic name for each issuer with its corresponding X.509 certificate. The list of well-known issuers is typically built at startup time by the issuer name registry. The list used by the is specified in the application configuration file. + +- The property contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. You can examine the property to determine the entity that originally issued the claim. The name is taken from the list of well-known issuers maintained by the issuer name registry, as in the case of the property. + + + +## Examples + The following example extracts the claims associated to the authenticated user performing an HTTP request and writes them in the HTTP response. The current user is read from the as a and the claims are read from it. The claims are then written to the object. + +```csharp +ClaimsPrincipal principal = HttpContext.Current.User as ClaimsPrincipal; +if (null != principal) +{ + foreach (Claim claim in principal.Claims) + { + Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "
"); + } + +} + ``` ]]> @@ -152,7 +152,7 @@ if (null != principal) . ]]> @@ -366,7 +366,7 @@ if (null != principal) property is set to `null`. The and properties are set to . The property is set to ]]> @@ -430,7 +430,7 @@ if (null != principal) property is set to `null`. The and properties are set to . ]]> @@ -503,7 +503,7 @@ if (null != principal) property is set to `null`. The property is set according to the value of the `issuer` parameter. ]]> @@ -578,7 +578,7 @@ if (null != principal) property is set to `null`. ]]> @@ -712,7 +712,7 @@ if (null != principal) property of the new object is set to `null`. ]]> @@ -772,7 +772,7 @@ if (null != principal) property of the new object is set to the value of the `identity` parameter. ]]> @@ -827,7 +827,7 @@ if (null != principal) property is typically set when calling . ]]> @@ -875,7 +875,7 @@ if (null != principal) property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. ]]> @@ -925,11 +925,11 @@ if (null != principal) property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. - +## Remarks + Contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. + + The value of the property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. + Except for delegation and federation scenarios, the property and the property will usually have the same value. If the value of the property differs from the value of the property, the claim was first issued by the original issuer and was subsequently re-issued by the issuer. ]]> @@ -979,7 +979,7 @@ if (null != principal) property provides a dictionary of name-value pairs that allows metadata or other information about the claim to be associated with it. For claims generated from SAML tokens, this dictionary may contain keys given by the constants in the class. ]]> @@ -1035,7 +1035,7 @@ if (null != principal) , which contains a collection of claims that describe it. ]]> @@ -1084,7 +1084,7 @@ if (null != principal) and properties in the following format:."Type: Value". ]]> @@ -1132,7 +1132,7 @@ if (null != principal) property provides the semantic content of the claim, that is, it states what the claim is about. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The claim type is typically a URI; however, you are not limited to any specific format other than that it must be representable as a string. The only general requirement is that the claim issuer and the claim consumer must agree about the meaning of the claim. Constants for the well-known claim types used by Windows Identity Foundation (WIF) are available through the class. The claim value is provided by the property. ]]> @@ -1180,9 +1180,9 @@ if (null != principal) property provides the underlying syntactic type information about the value. The property provides the semantic information about the value; that is, it provides the meaning of the value and tells a claim consumer how to interpret it. ]]> @@ -1232,7 +1232,7 @@ if (null != principal) property contains a string that identifies the type information of the value. This property can be used to understand the format of the value and to provide information about how to serialize and deserialize the value. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized and deserialized from a string. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml index 7b233498c40..63e775eba79 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml @@ -77,17 +77,17 @@ Initializes a new instance of the class with default values. - || -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| - + +|Property|Default value| +|--------------|-------------------| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| + ]]> @@ -137,17 +137,17 @@ The CSP parameters to describe which signing key to use. Initializes a new instance of the class from a persisted key. - || -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| - + +|Property|Default value| +|--------------|-------------------| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| + > [!IMPORTANT] > This method is only supported on .NET Framework. Its use on .NET Core throws a . @@ -187,16 +187,16 @@ The scheme to use for identifying which signing certificate was used. Initializes a new instance of the class with a specified subject identifier type. - |2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| - + +|Property|Default value| +|--------------|-------------------| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| + ]]> @@ -233,19 +233,19 @@ The certificate whose private key will be used to sign a message. Initializes a new instance of the class with a specified signer certificate. - || -||2.16.840.1.101.3.4.2.1 (SHA-256)| -||| - - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. - + +|Property|Default value| +|--------------|-------------------| +||| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +||| + + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + ]]> @@ -284,18 +284,18 @@ The certificate whose private key will be used to sign a message. Initializes a new instance of the class with a specified signer certificate and subject identifier type. - |2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| - - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. - + +|Property|Default value| +|--------------|-------------------| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| + + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + ]]> @@ -334,18 +334,18 @@ The private key object to use when signing the message. Initializes a new instance of the class with a specified signer certificate, subject identifier type, and private key object. - |2.16.840.1.101.3.4.2.1 (SHA-256)| -|| if is ,

otherwise| - - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. - + +|Property|Default value| +|--------------|-------------------| +||2.16.840.1.101.3.4.2.1 (SHA-256)| +|| if is ,

otherwise| + + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + This constructor does not validate that the `privateKey` parameter corresponds to the public key in `certificate`. If the keys don't match, the class and method throw a during the signing process. ]]> @@ -459,11 +459,11 @@ Gets a collection of certificates which are considered with and . A collection of certificates which are considered with and . - via when the indicates that more than one certificate should be included. Any certificate which is part of this collection that is not relevant to the value is ignored. - + via when the indicates that more than one certificate should be included. Any certificate that is part of this collection that is not relevant to the value is ignored. + ]]> @@ -507,11 +507,11 @@ Gets or sets the algorithm identifier for the hash algorithm to use with the signature. The algorithm identifier for the hash algorithm to use with the signature. - . - + . + ]]> @@ -647,13 +647,13 @@ Gets a collections of attributes to associate with this signature that are also protected by the signature. A collections of attributes to associate with this signature that are also protected by the signature. - collection retrieved by the property is the signing time attribute. - - A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. - + collection retrieved by the property is the signing time attribute. + + A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. + ]]> @@ -731,11 +731,11 @@ Gets a collections of attributes to associate with this signature that are not protected by the signature. A collections of attributes to associate with this signature that are not protected by the signature. - collection retrieved by the property is a countersignature. - + collection retrieved by the property is a countersignature. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml index ea5ec51b5fe..f016a7a6c8c 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml @@ -518,7 +518,7 @@ ## Remarks This method exists for compatibility with the PKCS#12 specification, but its use is not recommended for purposes other than testing. - When building a PFX that can be used by the overloads of or which do not accept a password parameter, use the method with as the password. + When building a PFX that can be used by the overloads of or that do not accept a password parameter, use the method with as the password. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12CertBag.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12CertBag.xml index 992fa6a0671..dc2cc8d6031 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12CertBag.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12CertBag.xml @@ -62,7 +62,7 @@ - Gets the Object Identifier (OID) which identifies the content type of the encoded certificte value. - The Object Identifier (OID) which identifies the content type of the encoded certificate value. + Gets the Object Identifier (OID) that identifies the content type of the encoded certificte value. + The Object Identifier (OID) that identifies the content type of the encoded certificate value. class, via the and members. This type does not have special support for SDSI certificates, but callers expecting an SDSI certificate (or a certificate type defined after IETF RFC 7292) can process the value directly via the property. diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml index a034782df53..2d297908b75 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12Info.xml @@ -93,13 +93,13 @@ The data to interpret as a PKCS#12 PFX. - When this method returns, contains a value that indicates the number of bytes from which were read by this method. This parameter is treated as uninitialized. + When this method returns, contains a value that indicates the number of bytes from that were read by this method. This parameter is treated as uninitialized. to store without making a defensive copy; otherwise, . The default is . Reads the provided data as a PKCS#12 PFX and returns an object view of the contents. An object view of the PKCS#12 PFX decoded from the input. - The contents of the parameter were not successfully decoded as a PKCS#12 PFX. @@ -150,14 +150,14 @@ Attempts to verify the integrity of the contents with a password. - . + Therefore, there is no guarantee that a password that results in a `true` return from this method will succeed on a call to . ]]> @@ -194,9 +194,9 @@ if the password successfully verifies the integrity of the contents; if the password is not correct or the contents have been altered. - .Empty` represents the `null` password and `String.Empty.AsSpan()` represents the "empty" password. If one of those two values returns `true`, the other won't. @@ -239,9 +239,9 @@ if the password successfully verifies the integrity of the contents; if the password is not correct or the contents have been altered. - returns `false`, and vice versa. diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml index 2b77bff6f3e..6887520f4dd 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SafeContents.xml @@ -83,7 +83,7 @@ The certificate to add. Adds a certificate to the SafeContents via a new and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -119,7 +119,7 @@ The asymmetric private key to add. Adds an asymmetric private key to the SafeContents via a new and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -157,15 +157,15 @@ The nested contents to add to the SafeContents. Adds a nested SafeContents to the SafeContents via a new and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. - The parameter is . @@ -202,11 +202,11 @@ The SafeBag value to add. Adds a SafeBag to the SafeContents. - The parameter is . @@ -247,10 +247,10 @@ - The Object Identifier (OID) which identifies the data type of the secret value. + The Object Identifier (OID) that identifies the data type of the secret value. The BER-encoded value representing the secret to add. Adds an ASN.1 BER-encoded value with a specified type identifier to the SafeContents via a new and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -297,7 +297,7 @@ The bytes to use as a password when encrypting the key material. The password-based encryption (PBE) parameters to use when encrypting the key material. Adds an encrypted asymmetric private key to the SafeContents via a new from a byte-based password in an array and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -346,7 +346,7 @@ The bytes to use as a password when encrypting the key material. The password-based encryption (PBE) parameters to use when encrypting the key material. Adds an encrypted asymmetric private key to the SafeContents via a new from a byte-based password in a span and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -395,7 +395,7 @@ The password to use when encrypting the key material. The password-based encryption (PBE) parameters to use when encrypting the key material. Adds an encrypted asymmetric private key to the SafeContents via a new from a character-based password in a span and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -445,7 +445,7 @@ The password to use when encrypting the key material. The password-based encryption (PBE) parameters to use when encrypting the key material. Adds an encrypted asymmetric private key to the SafeContents via a new from a character-based password in a string and returns the newly created bag instance. - The bag instance which was added to the SafeContents. + The bag instance that was added to the SafeContents. To be added. The parameter is . This instance is read-only. @@ -513,9 +513,9 @@ The bytes to use as a password for decrypting the encrypted contents. Decrypts the contents of this SafeContents value using a byte-based password from an array. - The bytes to use as a password for decrypting the encrypted contents. Decrypts the contents of this SafeContents value using a byte-based password from a span. - The password to use for decrypting the encrypted contents. Decrypts the contents of this SafeContents value using a character-based password from a span. - @@ -648,9 +648,9 @@ The contents were not successfully decrypted. The password to use for decrypting the encrypted contents. Decrypts the contents of this SafeContents value using a character-based password from a string. - @@ -721,9 +721,9 @@ The contents were not successfully decrypted. if this value is in a read-only state; otherwise, . The default value is . - is read-only when the value is created to represent previously encoded values, such as from or the encoding operation internal to . diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml index e5cca49ce89..46b79099444 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12SecretBag.xml @@ -49,8 +49,8 @@ - Gets the Object Identifier (OID) which identifies the data type of the secret value. - The Object Identifier (OID) which identifies the data type of the secret value. + Gets the Object Identifier (OID) that identifies the data type of the secret value. + The Object Identifier (OID) that identifies the data type of the secret value. To be added. diff --git a/xml/System.Security.Cryptography.Pkcs/Rfc3161TimestampToken.xml b/xml/System.Security.Cryptography.Pkcs/Rfc3161TimestampToken.xml index 97175d9c0f5..b3b3ce10533 100644 --- a/xml/System.Security.Cryptography.Pkcs/Rfc3161TimestampToken.xml +++ b/xml/System.Security.Cryptography.Pkcs/Rfc3161TimestampToken.xml @@ -199,7 +199,7 @@ The value from calling The data to verify against this time-stamp token. - When this method returns, the certificate from the Timestamp Authority (TSA) which signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. + When this method returns, the certificate from the Timestamp Authority (TSA) that signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. An optional collection of certificates to consider as the Timestamp Authority (TSA) certificates, in addition to any certificates that may be included within the token. Verifies that the current token is a valid time-stamp token for the provided data. @@ -266,7 +266,7 @@ If the digest does not match, or the TSA certificate could not be determined, th The cryptographic hash to verify against this time-stamp token. The algorithm which produced . - When this method returns, the certificate from the Timestamp Authority (TSA) which signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. + When this method returns, the certificate from the Timestamp Authority (TSA) that signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. An optional collection of certificates to consider as the Timestamp Authority (TSA) certificates, in addition to any certificates that may be included within the token. Verifies that the current token is a valid time-stamp token for the provided data hash and algorithm identifier. @@ -340,7 +340,7 @@ If the digest does not match, the algorithm does not match, or the TSA certifica The cryptographic hash to verify against this time-stamp token. The OID of the hash algorithm. - When this method returns, the certificate from the Timestamp Authority (TSA) which signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. + When this method returns, the certificate from the Timestamp Authority (TSA) that signed this token, or if a signer certificate cannot be determined. This parameter is treated as uninitialized. An optional collection of certificates to consider as the Timestamp Authority (TSA) certificates, in addition to any certificates that may be included within the token. Verifies that the current token is a valid time-stamp token for the provided data hash and algorithm identifier. diff --git a/xml/System.Security.Cryptography.X509Certificates/CertificateRequest.xml b/xml/System.Security.Cryptography.X509Certificates/CertificateRequest.xml index 968be46de02..3bdfae5ac92 100644 --- a/xml/System.Security.Cryptography.X509Certificates/CertificateRequest.xml +++ b/xml/System.Security.Cryptography.X509Certificates/CertificateRequest.xml @@ -1148,7 +1148,7 @@ This object was created with a constructor which did not accept a signing key. A bitwise combination of the enumeration values that specifies how to load the request. The RSA Signature Padding to use when creating a certificate from this request. For RSA signing certificates using the default signature generator, this parameter is required; otherwise, this parameter is ignored. Loads a binary PKCS#10 signing request as a new CertificateRequest instance. - A CertificateRequest instance which contains the information from the signing request. + A CertificateRequest instance that contains the information from the signing request. To be added. . is or . @@ -1215,7 +1215,7 @@ This object was created with a constructor which did not accept a signing key. A bitwise combination of the enumeration values that specifies how to load the request. The RSA Signature Padding to use when creating a certificate from this request. For RSA signing certificates using the default signature generator, this parameter is required; otherwise, this parameter is ignored. Loads a binary PKCS#10 signing request as a new CertificateRequest instance. - A CertificateRequest instance which contains the information from the signing request. + A CertificateRequest instance that contains the information from the signing request. To be added. . is or . @@ -1280,7 +1280,7 @@ This object was created with a constructor which did not accept a signing key. A bitwise combination of the enumeration values that specifies how to load the request. The RSA Signature Padding to use when creating a certificate from this request. For RSA signing certificates using the default signature generator, this parameter is required; otherwise, this parameter is ignored. Loads the first PEM-encoded PKCS#10 signing request from as a new CertificateRequest instance. - A CertificateRequest instance which contains the information from the signing request. + A CertificateRequest instance that contains the information from the signing request. To be added. . is or . @@ -1290,7 +1290,7 @@ This object was created with a constructor which did not accept a signing key. specifies a value that is not supported. does not contain a PKCS#10 signing request. - + -or- is not a valid PKCS#10 signing request. @@ -1343,7 +1343,7 @@ This object was created with a constructor which did not accept a signing key. A bitwise combination of the enumeration values that specifies how to load the request. The RSA Signature Padding to use when creating a certificate from this request. For RSA signing certificates using the default signature generator, this parameter is required; otherwise, this parameter is ignored. Loads the first PEM-encoded PKCS#10 signing request from as a new CertificateRequest instance. - A CertificateRequest instance which contains the information from the signing request. + A CertificateRequest instance that contains the information from the signing request. To be added. . is or . @@ -1353,7 +1353,7 @@ This object was created with a constructor which did not accept a signing key. specifies a value that is not supported. does not contain a PKCS#10 signing request. - + -or- is not a valid PKCS#10 signing request. diff --git a/xml/System.Security.Cryptography.Xml/CipherData.xml b/xml/System.Security.Cryptography.Xml/CipherData.xml index a1dea8c12a2..64bf1c53e24 100644 --- a/xml/System.Security.Cryptography.Xml/CipherData.xml +++ b/xml/System.Security.Cryptography.Xml/CipherData.xml @@ -38,25 +38,25 @@ Represents the element in XML encryption. This class cannot be inherited. - class represents the `` element in XML encryption. It is a required element that provides the encrypted data. It must either contain the encrypted data as base64-encoded text of the `` element, or provide a reference to an external location containing the encrypted data using the `` element. - - In many cases, you do not need to directly create a new instance of the class. The , , and classes create instances for you. - + class represents the `` element in XML encryption. It is a required element that provides the encrypted data. It must either contain the encrypted data as base64-encoded text of the `` element, or provide a reference to an external location containing the encrypted data using the `` element. + + In many cases, you do not need to directly create a new instance of the class. The , , and classes create instances for you. + > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. - - - -## Examples - The following code example uses the class to create an `` element that contains a `` element, and then writes the XML to an XML file. - +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. + + + +## Examples + The following code example uses the class to create an `` element that contains a `` element, and then writes the XML to an XML file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/cpp/encrypteddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/Overview/encrypteddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet1"::: + ]]> @@ -97,20 +97,20 @@ Initializes a new instance of the class. - object that represents the `` element in XML encryption. The `` element is a required element in XML encryption. - - - -## Examples - The following code example shows how to create a new instance of the class. The entire sample can be found in the class topic. - + object that represents the `` element in XML encryption. The `` element is a required element in XML encryption. + + + +## Examples + The following code example shows how to create a new instance of the class. The entire sample can be found in the class topic. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/cpp/encrypteddata.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/Overview/encrypteddata.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet2"::: + ]]> @@ -146,23 +146,23 @@ The encrypted data to use for the element. Initializes a new instance of the class using a byte array as the value. - object that represents the `` element in XML encryption. The constructor assigns the `cipherValue` value to the property as the actual encrypted data. - + object that represents the `` element in XML encryption. The constructor assigns the `cipherValue` value to the property as the actual encrypted data. + > [!NOTE] -> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. - - - -## Examples - The following code example shows how to create a new instance of the class. - +> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. + + + +## Examples + The following code example shows how to create a new instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/CPP/encrypteddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/encrypteddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/VB/encrypteddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/VB/encrypteddata.vb" id="Snippet1"::: + ]]> The parameter is . @@ -200,23 +200,23 @@ The object to use. Initializes a new instance of the class using a object. - object that represents the `` element in XML encryption and assigns the `cipherReference` value to the property. The object represents the `` element, which provides the location of the encrypted data. - + object that represents the `` element in XML encryption and assigns the `cipherReference` value to the property. The object represents the `` element, which provides the location of the encrypted data. + > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. - - - -## Examples - The following code example shows how to create a new instance of the class using information. - +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. + + + +## Examples + The following code example shows how to create a new instance of the class using information. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> The parameter is . @@ -255,23 +255,23 @@ Gets or sets the element. A object. - ` element identifies a source which, when processed, yields the encrypted data. For more information about this element, see . - + ` element identifies a source that, when processed, yields the encrypted data. For more information about this element, see . + > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. - - - -## Examples - The following code example shows how to create a new instance of the class using information. - +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. + + + +## Examples + The following code example shows how to create a new instance of the class using information. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> The property was set to . @@ -310,23 +310,23 @@ Gets or sets the element. A byte array that represents the element. - [!NOTE] -> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. - - - -## Examples - The following code example shows how to create a new instance of the class. - +> The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. + + + +## Examples + The following code example shows how to create a new instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/CPP/encrypteddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/encrypteddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/VB/encrypteddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.EncryptedData2/VB/encrypteddata.vb" id="Snippet1"::: + ]]> The property was set to . @@ -365,20 +365,20 @@ Gets the XML values for the object. A object that represents the XML information for the object. - object. - - - -## Examples - The following code example demonstrates how to create a new instance of the object. - + object. + + + +## Examples + The following code example demonstrates how to create a new instance of the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/cpp/encrypteddata.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/Overview/encrypteddata.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptgraphy.Xml.EncryptedData/VB/encrypteddata.vb" id="Snippet2"::: + ]]> The property and the property are . @@ -428,11 +428,11 @@ An that represents the XML data to load. Loads XML data from an into a object. - method overwrites existing XML elements with the `value` parameter. - + method overwrites existing XML elements with the `value` parameter. + ]]> The parameter is . diff --git a/xml/System.Security.Cryptography.Xml/CipherReference.xml b/xml/System.Security.Cryptography.Xml/CipherReference.xml index 1f7c5928089..6d1def7537d 100644 --- a/xml/System.Security.Cryptography.Xml/CipherReference.xml +++ b/xml/System.Security.Cryptography.Xml/CipherReference.xml @@ -38,34 +38,34 @@ Represents the element in XML encryption. This class cannot be inherited. - ` element in XML encryption. It identifies a source which, when processed, yields the encrypted data. - - The actual encrypted data referenced by the `` is obtained by the following process. The ` URI` property contains a Uniform Resource Identifier (URI) that is dereferenced. If the `` element also contains a transform chain, the data resulting from dereferencing the URI is transformed as specified to produce the encrypted data. For example, if the encrypted data is base64-encoded within an XML document, the transforms would specify an XPath expression followed by a base64 decoding so the encrypted data can be extracted. - - The syntax of the URI and transforms is similar to that of XML digital signatures. However, in XML digital signatures, both generation and validation processing start with the same source data and perform that transform in the same order. In XML encryption, the decrypting application has only the encrypted data and the specified transforms. The transforms are enumerated in the order necessary to obtain the encrypted data. - - **Note** By default, you cannot dereference cipher references from documents with unknown sources, such as files from a Web site, because the property is **null**. For example, when you attempt to decrypt a file containing a `` element that references a file on the Web, a is thrown, even if the request is made by a fully trusted assembly. - - If you are sure the documents you are decrypting can be trusted, you can change this behavior for fully trusted applications by using the following code: - -``` -Evidence ev = new Evidence(); -ev.AddHost (new Zone(SecurityZone.MyComputer)); -EncryptedXml exml = new EncryptedXml(doc, ev); -``` - - - -## Examples - The following code example creates a new instance of . - + ` element in XML encryption. It identifies a source that, when processed, yields the encrypted data. + + The actual encrypted data referenced by the `` is obtained by the following process. The ` URI` property contains a Uniform Resource Identifier (URI) that is dereferenced. If the `` element also contains a transform chain, the data resulting from dereferencing the URI is transformed as specified to produce the encrypted data. For example, if the encrypted data is base64-encoded within an XML document, the transforms would specify an XPath expression followed by a base64 decoding so the encrypted data can be extracted. + + The syntax of the URI and transforms is similar to that of XML digital signatures. However, in XML digital signatures, both generation and validation processing start with the same source data and perform that transform in the same order. In XML encryption, the decrypting application has only the encrypted data and the specified transforms. The transforms are enumerated in the order necessary to obtain the encrypted data. + + **Note** By default, you cannot dereference cipher references from documents with unknown sources, such as files from a Web site, because the property is **null**. For example, when you attempt to decrypt a file containing a `` element that references a file on the Web, a is thrown, even if the request is made by a fully trusted assembly. + + If you are sure the documents you are decrypting can be trusted, you can change this behavior for fully trusted applications by using the following code: + +``` +Evidence ev = new Evidence(); +ev.AddHost (new Zone(SecurityZone.MyComputer)); +EncryptedXml exml = new EncryptedXml(doc, ev); +``` + + + +## Examples + The following code example creates a new instance of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> @@ -78,11 +78,11 @@ EncryptedXml exml = new EncryptedXml(doc, ev); Initializes a new instance of the class. - object that provides reference information for a object. The reference information provides the location of the encrypted data. - + object that provides reference information for a object. The reference information provides the location of the encrypted data. + ]]> @@ -114,20 +114,20 @@ EncryptedXml exml = new EncryptedXml(doc, ev); Initializes a new instance of the class. - object that provides reference information for a object. - - - -## Examples - The following code example creates a new instance of . - + object that provides reference information for a object. + + + +## Examples + The following code example creates a new instance of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> @@ -163,42 +163,42 @@ EncryptedXml exml = new EncryptedXml(doc, ev); A Uniform Resource Identifier (URI) pointing to the encrypted data. Initializes a new instance of the class using the specified Uniform Resource Identifier (URI). - object using a Uniform Resource Identifier (URI) that points to the encrypted data. The object is then used to provide reference information for a object. - - You can use a URI to designate an XML file containing encrypted data. For example: - - `String uri = "http://www.woodgrovebank.com/document.xml";` - - You can also use a partial URI to designate that only a portion of an XML document is to be encrypted. For example, assume that an XML document named document.xml contains two `MyForm` elements as shown in the following XML code example: - - `` - - `` - - `` - - `` - - `` - - `` - - You can encrypt only the content in `Form2` using a URI such as the following: - - `String uri = "http://www.woodgrovebank.com/document.xml#Form2";` - - - -## Examples - The following code example creates a new instance of . - + object using a Uniform Resource Identifier (URI) that points to the encrypted data. The object is then used to provide reference information for a object. + + You can use a URI to designate an XML file containing encrypted data. For example: + + `String uri = "http://www.woodgrovebank.com/document.xml";` + + You can also use a partial URI to designate that only a portion of an XML document is to be encrypted. For example, assume that an XML document named document.xml contains two `MyForm` elements as shown in the following XML code example: + + `` + + `` + + `` + + `` + + `` + + `` + + You can encrypt only the content in `Form2` using a URI such as the following: + + `String uri = "http://www.woodgrovebank.com/document.xml#Form2";` + + + +## Examples + The following code example creates a new instance of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> @@ -236,20 +236,20 @@ EncryptedXml exml = new EncryptedXml(doc, ev); A object that describes transforms to do on the encrypted data. Initializes a new instance of the class using the specified Uniform Resource Identifier (URI) and transform chain information. - object using a Uniform Resource Identifier (URI) and transform chain to indicate the encrypted data. The object is then used to provide reference information for a object. - - - -## Examples - The following code example creates a new instance of . - + object using a Uniform Resource Identifier (URI) and transform chain to indicate the encrypted data. The object is then used to provide reference information for a object. + + + +## Examples + The following code example creates a new instance of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/cryptography.Xml.CipherReference/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherData/.ctor/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/cryptography.Xml.CipherReference/VB/example.vb" id="Snippet1"::: + ]]> @@ -286,20 +286,20 @@ EncryptedXml exml = new EncryptedXml(doc, ev); Returns the XML representation of a object. An that represents the element in XML encryption. - ` element in XML. - - - -## Examples - The following code example shows one way to use the method. - + ` element in XML. + + + +## Examples + The following code example shows one way to use the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CipherReference2/CPP/example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/CipherReference/GetXml/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CipherReference2/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CipherReference2/VB/example.vb" id="Snippet1"::: + ]]> The value is . @@ -349,11 +349,11 @@ EncryptedXml exml = new EncryptedXml(doc, ev); An object that represents an XML element to use as the reference. Loads XML information into the element in XML encryption. - object. - + object. + ]]> The provided is . diff --git a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml index b662bd1cdb6..7c0cb9d4e2f 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml @@ -38,60 +38,60 @@ Represents the process model for implementing XML encryption. - class is the main class used for XML encryption in the .NET Framework. XML Encryption is a standards-based, interoperable way to encrypt all or part of an XML document or any arbitrary data. The .NET Framework XML encryption classes implement the World Wide Web Consortium (W3C) [XML Encryption Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/) specification. - - Use the class whenever you need to share encrypted XML data between applications or organizations in a standard way. Any data encrypted using this class can be decrypted by any implementation of the W3C specification for XML encryption. - - XML encryption replaces any plain text XML element or document with the `` element, which contains an encrypted (or cipher text) representation of plain text XML or any arbitrary data. The `` element can optionally contain information about where to find a key that will decrypt the cipher text, and which cryptographic algorithm was used to encrypt the plain text. - - The `` element is similar to the `` element in style and usage, except that it allows you to encrypt a key that will decrypt the value of the `` element. Note that the `` element and the `` element will never contain an unencrypted key. - - Use one of the following methods to exchange key information: - -- Do not include any key information. If you choose this option, both parties must agree on an algorithm and key before they exchange encrypted data. - -- Include the location of the key in the Uniform Resource Identifier (URI) attribute of the `` element. Both parties must agree on the key location ahead of time and this location must be kept secret. - -- Include a string name that maps to a key in the `` element. Both parties must agree on the key name mapping before they exchange encrypted data and this mapping must be kept secret. - -- Include an encrypted key in the `` element. Both parties must agree on the key that decrypts the encrypted key before they exchange encrypted data. You can optionally include a name or location of the key that will decrypt the key in the `` element. - - - -## Examples - The following code example demonstrates how to create a simple utility class that uses the algorithm to encrypt an XML document. - + class is the main class used for XML encryption in the .NET Framework. XML Encryption is a standards-based, interoperable way to encrypt all or part of an XML document or any arbitrary data. The .NET Framework XML encryption classes implement the World Wide Web Consortium (W3C) [XML Encryption Syntax and Processing Version 1.0](https://www.w3.org/TR/2002/REC-xmlenc-core-20021210/) specification. + + Use the class whenever you need to share encrypted XML data between applications or organizations in a standard way. Any data encrypted using this class can be decrypted by any implementation of the W3C specification for XML encryption. + + XML encryption replaces any plain text XML element or document with the `` element, which contains an encrypted (or cipher text) representation of plain text XML or any arbitrary data. The `` element can optionally contain information about where to find a key that will decrypt the cipher text, and which cryptographic algorithm was used to encrypt the plain text. + + The `` element is similar to the `` element in style and usage, except that it allows you to encrypt a key that will decrypt the value of the `` element. Note that the `` element and the `` element will never contain an unencrypted key. + + Use one of the following methods to exchange key information: + +- Do not include any key information. If you choose this option, both parties must agree on an algorithm and key before they exchange encrypted data. + +- Include the location of the key in the Uniform Resource Identifier (URI) attribute of the `` element. Both parties must agree on the key location ahead of time and this location must be kept secret. + +- Include a string name that maps to a key in the `` element. Both parties must agree on the key name mapping before they exchange encrypted data and this mapping must be kept secret. + +- Include an encrypted key in the `` element. Both parties must agree on the key that decrypts the encrypted key before they exchange encrypted data. You can optionally include a name or location of the key that will decrypt the key in the `` element. + + + +## Examples + The following code example demonstrates how to create a simple utility class that uses the algorithm to encrypt an XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.MainXMLEncDecryptDataOOP/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.MainXMLEncDecryptDataOOP/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.MainXMLEncDecryptDataOOP/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/CPP/Cryptography.XML.XMLEncMapKey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/CPP/Cryptography.XML.XMLEncMapKeyX509.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: + ]]> @@ -104,33 +104,33 @@ Initializes a new instance of the class. - @@ -172,38 +172,38 @@ Initializes a new instance of the class. - @@ -249,26 +249,26 @@ An object used to initialize the object. Initializes a new instance of the class using the specified XML document. - object when you want to specify the XML document to encrypt. The `document` parameter comprises the XML elements that later form the encrypted XML. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. - + object when you want to specify the XML document to encrypt. The `document` parameter comprises the XML elements that later form the encrypted XML. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/CPP/Cryptography.XML.XMLEncMapKey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + ]]> @@ -324,11 +324,11 @@ An object associated with the object. Initializes a new instance of the class using the specified XML document and evidence. - object when you want to specify the XML document to encrypt and provide security evidence. The `document` parameter comprises the XML elements that later form the encrypted XML. - + object when you want to specify the XML document to encrypt and provide security evidence. The `document` parameter comprises the XML elements that later form the encrypted XML. + ]]> @@ -369,28 +369,28 @@ The symmetric key to map to . Defines a mapping between a key name and a symmetric key or an asymmetric key. - method allows you to map a symmetric key or an asymmetric key to a string name. This method adds the values of the `keyName` and `keyObject` parameters to a table of valid key name mappings. - - Use the method to clear the key name mappings table. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. - + method allows you to map a symmetric key or an asymmetric key to a string name. This method adds the values of the `keyName` and `keyObject` parameters to a table of valid key name mappings. + + Use the method to clear the key name mappings table. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/CPP/Cryptography.XML.XMLEncMinimalDecrypt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/AddKeyNameMapping/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . The value of the parameter is not an RSA algorithm or a symmetric key. @@ -426,11 +426,11 @@ Resets all key name mapping. - method. - + method. + ]]> @@ -472,28 +472,28 @@ Decrypts an element using the specified symmetric algorithm. A byte array that contains the raw decrypted plain text. - method to decrypt an element using a symmetric key. - - Note that the method only decrypts top-level `` tags. In cases where one or more `` tags have been encrypted and are contained within higher level `` tags, you can call the method separately for each one. See the method for a code example. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + method to decrypt an element using a symmetric key. + + Note that the method only decrypts top-level `` tags. In cases where one or more `` tags have been encrypted and are contained within higher level `` tags, you can call the method separately for each one. See the method for a code example. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -538,38 +538,38 @@ Decrypts all elements of the XML document that were specified during initialization of the class. - method decrypts all `` elements of the XML document loaded during initialization. After you call this method, all `` elements in the document are replaced with plain text versions. - - The method decrypts only top-level `` elements. If you need to decrypt a super-encrypted document (a document that is encrypted more than once), you must call the method repeatedly until all the `` elements have been decrypted. - + method decrypts all `` elements of the XML document loaded during initialization. After you call this method, all `` elements in the document are replaced with plain text versions. + + The method decrypts only top-level `` elements. If you need to decrypt a super-encrypted document (a document that is encrypted more than once), you must call the method repeatedly until all the `` elements have been decrypted. + > [!NOTE] -> The method decrypts only valid XML data. To decrypt arbitrary data, use the method. - - To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - +> The method decrypts only valid XML data. To decrypt arbitrary data, use the method. + + To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/CPP/Cryptography.XML.XMLEncMapKeyX509.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to decrypt a high level `` tag that contains another encrypted `` tag. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to decrypt a high level `` tag that contains another encrypted `` tag. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/DecryptDocument/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/Cryptography.XML.EncryptedDocument.DecryptDocument-SuperEncryption/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/Cryptography.XML.EncryptedDocument.DecryptDocument-SuperEncryption/VB/sample.vb" id="Snippet1"::: + ]]> The cryptographic key used to decrypt the document was not found. @@ -627,13 +627,13 @@ Determines the key represented by the element. A byte array that contains the key. - method decrypts an encrypted key contained within the `` element of an XML document. - - This recursive method finds the key represented by the object. Note that an object can contain another object that specifies its value. - + method decrypts an encrypted key contained within the `` element of an XML document. + + This recursive method finds the key represented by the object. Note that an object can contain another object that specifies its value. + ]]> The value of the parameter is . @@ -648,11 +648,11 @@ Decrypts an element. - method to decrypt an `` element and retrieve the key used to decrypt that element. - + method to decrypt an `` element and retrieve the key used to decrypt that element. + ]]> @@ -694,17 +694,17 @@ Decrypts an element using a symmetric algorithm. A byte array that contains the plain text key. - method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). - + method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . The value of the element is not the Triple DES Key Wrap algorithm or the Advanced Encryption Standard (AES) Key Wrap algorithm (also called Rijndael). @@ -748,17 +748,17 @@ Decrypts an element using an asymmetric algorithm. A byte array that contains the plain text key. - method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `rsa` parameter that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP padding). - + method decrypts an encrypted key contained within the `` element of an XML document. This method accepts a value for the `rsa` parameter that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP padding). + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -800,11 +800,11 @@ Gets or sets the evidence of the object from which the object is constructed. An object. - object has any security evidence, you should add the evidence to the property. If you do not set this property, any associated objects will not be dereferenced because they will not be granted the required permission set. - + object has any security evidence, you should add the evidence to the property. If you do not set this property, any associated objects will not be dereferenced because they will not be granted the required permission set. + ]]> @@ -840,11 +840,11 @@ Gets or sets the encoding used for XML encryption. An object. - class, such as UTF-16 or ASCII. - + class, such as UTF-16 or ASCII. + ]]> @@ -857,21 +857,21 @@ Encrypts the outer XML of an element using the specified certificate or key in the key mapping table. - @@ -923,30 +923,30 @@ Encrypts the outer XML of an element using the specified X.509 certificate. An element that represents the encrypted XML data. - method is a convenient way to encrypt the outer XML of an element using a certificate. This method generates a 256-bit Advanced Encryption Standard (AES) session key to encrypt an XML element and then encrypts and signs the AES key using the object. The method then returns the resulting XML as an element. - - If you need more control over the encryption, so you can place the encrypted information into a `` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. - - To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. - + method is a convenient way to encrypt the outer XML of an element using a certificate. This method generates a 256-bit Advanced Encryption Standard (AES) session key to encrypt an XML element and then encrypts and signs the AES key using the object. The method then returns the resulting XML as an element. + + If you need more control over the encryption, so you can place the encrypted information into a `` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. + + To use XML Encryption with X.509 certificates, you must have the Microsoft Enhanced Cryptographic Provider installed and the X.509 certificate must use the Enhanced Provider. If you do not have the Microsoft Enhanced Cryptographic Provider installed or the X.509 certificate does not use the Enhanced Provider, a with an "Unknown Error" will be thrown when you decrypt an XML document. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using an X.509 certificate. This example creates a symmetric session key to encrypt the document and then uses the X.509 certificate to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/CPP/Cryptography.XML.XMLEncMapKeyX509.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKeyX509/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . The value of the parameter does not represent an RSA key algorithm. @@ -998,33 +998,33 @@ Encrypts the outer XML of an element using the specified key in the key mapping table. An object that represents the encrypted XML data. - ` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. - - For a list of all supported algorithms, see the list of constant fields associated with the class. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. - + ` element or specify whether the entire XML element or just its contents should be encrypted, use the method overloads. + + For a list of all supported algorithms, see the list of constant fields associated with the class. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/CPP/Cryptography.XML.XMLEncMinimalDecrypt.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/AddKeyNameMapping/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecrypt/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . - The value of the parameter does not match a registered key name pair. - - -or- - + The value of the parameter does not match a registered key name pair. + + -or- + The cryptographic key described by the parameter is not supported. @@ -1036,27 +1036,27 @@ Encrypts XML data using a symmetric algorithm. - @@ -1098,38 +1098,38 @@ Encrypts data in the specified byte array using the specified symmetric algorithm. A byte array of encrypted data. - ` element. This method assumes that the data specified in the `plaintext` parameter is a byte array that contains XML data. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + ` element. This method assumes that the data specified in the `plaintext` parameter is a byte array that contains XML data. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example embeds a key name in the encrypted XML document that the decrypting method uses to find the appropriate decryption key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/CPP/Cryptography.XML.XMLEncMapKey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: - - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMapKey/VB/sample.vb" id="Snippet1"::: + + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . The data could not be encrypted using the specified parameters. @@ -1174,26 +1174,26 @@ Encrypts the specified element or its contents using the specified symmetric algorithm. A byte array that contains the encrypted data. - ` element. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + ` element. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -1205,20 +1205,20 @@ Encrypts the key that a recipient uses to decrypt an element. - method to encrypt the key that a recipient uses to decrypt an `` element. This method places the encrypted key within an `` element. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + method to encrypt the key that a recipient uses to decrypt an `` element. This method places the encrypted key within an `` element. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + ]]> @@ -1260,19 +1260,19 @@ Encrypts a key using a symmetric algorithm that a recipient uses to decrypt an element. A byte array that represents the encrypted value of the parameter. - method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). - - Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. - + method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for the `symmetricAlgorithm` parameter that represents either the Triple DES algorithm or the AES key wrap algorithm (also called Rijndael). + + Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . The value of the parameter is not the Triple DES Key Wrap algorithm or the Advanced Encryption Standard (AES) Key Wrap algorithm (also called Rijndael). @@ -1316,28 +1316,28 @@ Encrypts the key that a recipient uses to decrypt an element. A byte array that represents the encrypted value of the parameter. - method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for `rsa` that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP). - - Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + method to encrypt the key that a recipient uses to decrypt an `` element. This method accepts a value for `rsa` that represents either the RSA PKCS#1 v1.5 algorithm or the RSA PKCS#1 type 2 algorithm (also called OAEP). + + Note that this method does not automatically place the encrypted key within an `` element. You must manually create the `` element within your document. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -1386,20 +1386,20 @@ Retrieves the decryption initialization vector (IV) from an object. A byte array that contains the decryption initialization vector (IV). - object, this method retrieves the decryption initialization vector (IV). The default behavior retrieves the IV as the first bytes of the byte array. - - For a list of Uniform Resource Identifier (URI) values supported by the `symmetricAlgorithmUri` parameter, see the list of constant fields associated with the class. - + object, this method retrieves the decryption initialization vector (IV). The default behavior retrieves the IV as the first bytes of the byte array. + + For a list of Uniform Resource Identifier (URI) values supported by the `symmetricAlgorithmUri` parameter, see the list of constant fields associated with the class. + ]]> The value of the parameter is . - The value of the parameter has an property that is null. - - -or- - + The value of the parameter has an property that is null. + + -or- + The value of the parameter is not a supported algorithm. @@ -1458,18 +1458,18 @@ Retrieves the decryption key from the specified object. A object associated with the decryption key. - object, this method looks for the decryption key that can be used to retrieve the plain text data. If a key name is specified, the method looks for the symmetric algorithm or asymmetric algorithm that is associated with the key name as defined in the key name mapping. Otherwise, if a retrieval method or an object is specified, the method loads the object and calls the method. - + object, this method looks for the decryption key that can be used to retrieve the plain text data. If a key name is specified, the method looks for the symmetric algorithm or asymmetric algorithm that is associated with the key name as defined in the key name mapping. Otherwise, if a retrieval method or an object is specified, the method loads the object and calls the method. + ]]> The value of the parameter is . - The encryptedData parameter has an property that is null. - - -or- - + The encryptedData parameter has an property that is null. + + -or- + The encrypted key cannot be retrieved using the specified parameters. @@ -1517,11 +1517,11 @@ Determines how to resolve internal Uniform Resource Identifier (URI) references. An object that contains an ID indicating how internal Uniform Resource Identifiers (URIs) are to be resolved. - method determines how to resolve internal Uniform Resource Identifiers (URIs). It looks for elements with a specified value or for elements with an ID attribute that has a specified value. - + method determines how to resolve internal Uniform Resource Identifiers (URIs). It looks for elements with a specified value or for elements with an ID attribute that has a specified value. + ]]> @@ -1557,11 +1557,11 @@ Gets or sets the cipher mode used for XML encryption. One of the values. - enumeration, such as Cipher Feedback (CFB) mode. - + enumeration, such as Cipher Feedback (CFB) mode. + ]]> @@ -1597,11 +1597,11 @@ Gets or sets the padding mode used for XML encryption. One of the values that specifies the type of padding used for encryption. - enumeration, such as ANSI X9.23 or PKCS#5. - + enumeration, such as ANSI X9.23 or PKCS#5. + ]]> @@ -1637,13 +1637,13 @@ Gets or sets the recipient of the encrypted key information. The recipient of the encrypted key information. - object referenced by a key name by examining the property. - - Use the property to identify the element that the current recipient can decrypt to retrieve a decryption key. - + object referenced by a key name by examining the property. + + Use the property to identify the element that the current recipient can decrypt to retrieve a decryption key. + ]]> @@ -1684,26 +1684,26 @@ The decrypted data to replace with. Replaces an element with a specified decrypted sequence of bytes. - method replaces an `` element with the value of the `decryptedData` parameter. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + method replaces an `` element with the value of the `decryptedData` parameter. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -1746,26 +1746,26 @@ to replace only the contents of the element; to replace the entire element. Replaces the specified element with the specified object. - method replaces the `inputElement` parameter with the value specified by the `encryptedData` parameter. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + method replaces the `inputElement` parameter with the value specified by the `encryptedData` parameter. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> - The value of the parameter is . - - -or- - + The value of the parameter is . + + -or- + The value of the parameter is . @@ -1807,11 +1807,11 @@ Gets or sets the object used by the Document Object Model (DOM) to resolve external XML references. An object. - object used to resolve external XML resources such as entities, document type definitions (DTDs), or schemas. - + object used to resolve external XML resources such as entities, document type definitions (DTDs), or schemas. + ]]> @@ -1843,7 +1843,7 @@ System.Int32 - Gets or sets the XML digital signature recursion depth to prevent infinite recursion and stack overflow. This might happen if the digital signature XML contains the URI which then points back to the original XML. + Gets or sets the XML digital signature recursion depth to prevent infinite recursion and stack overflow. This might happen if the digital signature XML contains the URI that then points back to the original XML. Returns . To be added. @@ -1878,11 +1878,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the 128-bit Advanced Encryption Standard (AES) Key Wrap algorithm (also known as the Rijndael Key Wrap algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#kw-aes128)`. - + field is `http://www.w3.org/(2001/04/xmlenc#kw-aes128)`. + ]]> @@ -1917,20 +1917,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the 128-bit Advanced Encryption Standard (AES) algorithm (also known as the Rijndael algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#aes128-cbc)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#aes128-cbc)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> @@ -1965,11 +1965,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the 192-bit Advanced Encryption Standard (AES) Key Wrap algorithm (also known as the Rijndael Key Wrap algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#kw-aes192)`. - + field is `http://www.w3.org/(2001/04/xmlenc#kw-aes192)`. + ]]> @@ -2004,20 +2004,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the 192-bit Advanced Encryption Standard (AES) algorithm (also known as the Rijndael algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#aes192-cbc)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#aes192-cbc)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2052,11 +2052,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the 256-bit Advanced Encryption Standard (AES) Key Wrap algorithm (also known as the Rijndael Key Wrap algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#kw-aes256)`. - + field is `http://www.w3.org/(2001/04/xmlenc#kw-aes256)`. + ]]> @@ -2091,20 +2091,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the 256-bit Advanced Encryption Standard (AES) algorithm (also known as the Rijndael algorithm). This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#aes256-cbc)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#aes256-cbc)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2139,20 +2139,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the Digital Encryption Standard (DES) algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#des-cbc)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#des-cbc)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2187,11 +2187,11 @@ Represents the namespace Uniform Resource Identifier (URI) for XML encryption element content. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#Content)`. - + field is `http://www.w3.org/(2001/04/xmlenc#Content)`. + ]]> @@ -2226,20 +2226,20 @@ Represents the namespace Uniform Resource Identifier (URI) for an XML encryption element. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#Element)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#Element)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2274,11 +2274,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the XML encryption element. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#EncryptedKey)`. - + field is `http://www.w3.org/(2001/04/xmlenc#EncryptedKey)`. + ]]> @@ -2313,11 +2313,11 @@ Represents the namespace Uniform Resource Identifier (URI) for XML encryption syntax and processing. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#)`. - + field is `http://www.w3.org/(2001/04/xmlenc#)`. + ]]> @@ -2352,20 +2352,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the RSA Public Key Cryptography Standard (PKCS) Version 1.5 algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#rsa-1_5)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#rsa-1_5)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/CPP/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncImbedKey/VB/sample.vb" id="Snippet1"::: + ]]> @@ -2400,11 +2400,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the RSA Optimal Asymmetric Encryption Padding (OAEP) encryption algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#rsa-oaep-mgf1p)`. - + field is `http://www.w3.org/(2001/04/xmlenc#rsa-oaep-mgf1p)`. + ]]> @@ -2439,11 +2439,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the SHA-256 algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#sha256)`. - + field is `http://www.w3.org/(2001/04/xmlenc#sha256)`. + ]]> @@ -2478,11 +2478,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the SHA-512 algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#sha512)`. - + field is `http://www.w3.org/(2001/04/xmlenc#sha512)`. + ]]> @@ -2517,11 +2517,11 @@ Represents the namespace Uniform Resource Identifier (URI) for the TRIPLEDES key wrap algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#kw-tripledes)`. - + field is `http://www.w3.org/(2001/04/xmlenc#kw-tripledes)`. + ]]> @@ -2556,20 +2556,20 @@ Represents the namespace Uniform Resource Identifier (URI) for the Triple DES algorithm. This field is constant. - field is `http://www.w3.org/(2001/04/xmlenc#tripledes-cbc)`. - - - -## Examples - The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. - + field is `http://www.w3.org/(2001/04/xmlenc#tripledes-cbc)`. + + + +## Examples + The following code example demonstrates how to encrypt an XML document using a symmetric key. This example does not include any key information in the encrypted XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/CPP/Cryptography.XML.XMLEncMinimalDecryptData.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.XML.XMLEncMinimalDecryptData/VB/sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography/DSAOpenSsl.xml b/xml/System.Security.Cryptography/DSAOpenSsl.xml index 6cad42133e3..6542083d1ba 100644 --- a/xml/System.Security.Cryptography/DSAOpenSsl.xml +++ b/xml/System.Security.Cryptography/DSAOpenSsl.xml @@ -105,7 +105,7 @@ DSAOpenSSL provides the FIPS 186-3 version of DSA. ## Remarks -This constructor does not generate a new DSA public/private keypair immediately, it just sets the size which will be used to generate a key when one is needed. +This constructor does not generate a new DSA public/private keypair immediately, it just sets the size that will be used to generate a key when one is needed. If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -166,7 +166,7 @@ If key is loaded via the method, or other key import method, the `keySize` provided to this constructor has no meaning. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml b/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml index 0f28366d864..edb385d473e 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanOpenSsl.xml @@ -40,9 +40,9 @@ Provides an implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm backed by OpenSSL. - factory methods instead of a specific derived implementation. @@ -94,11 +94,11 @@ This class should only be used directly when doing platform interop with the sys Initializes a new instance of the class with a default curve of NIST P-521/secp521r1. - method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -154,15 +154,15 @@ If key is loaded via the The size of the key to generate, when a key is needed. Initializes a new instance of the class defaulting to the NIST prime curve of the specified size. - constructor or the method. -This constructor does not generate a new public/private keypair immediately, it just sets the size which will be used to generate a key when one is needed. +This constructor does not generate a new public/private keypair immediately, it just sets the size that will be used to generate a key when one is needed. If key is loaded via the method, or other key import method, the key size from this constructor has no meaning. ]]> @@ -221,9 +221,9 @@ If key is loaded via the The OpenSSL EC_KEY* value to use as the key. Initializes a new instance of the class from an existing OpenSSL key represented as an EC_KEY*. - [!IMPORTANT] > OpenSSL supports multiple library versions being loaded within the same process. Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses. For more information, see . @@ -338,9 +338,9 @@ If key is loaded via the The OpenSSL EVP_PKEY* value to use as the key, represented as a . Initializes a new instance of the class from an existing OpenSSL key represented as an EVP_PKEY*. - [!IMPORTANT] > OpenSSL supports multiple library versions being loaded within the same process. Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses. For more information, see . ]]> @@ -561,8 +561,8 @@ This instance represents only a public key. Gets a representation of the cryptographic key. A representation of the cryptographic key. - object with its own lifetime. @@ -633,11 +633,11 @@ The objects returned by this method can safely be used even after this Exports the key used by the object into an object. The key and named curve parameters used by the object. - field contains named curve parameters; otherwise, it contains explicit parameters. - + field contains named curve parameters; otherwise, it contains explicit parameters. + ]]> The method cannot obtain curve values. @@ -668,11 +668,11 @@ The objects returned by this method can safely be used even after this The curve used to generate an ephemeral public/private key pair. Generates a new ephemeral public/private key pair for the specified curve. - method) and must not be implicit. - + method) and must not be implicit. + ]]> @@ -708,11 +708,11 @@ The objects returned by this method can safely be used even after this The curve's parameters to import. Imports the specified parameters for an object as a key into the current instance. - method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. - + method replaces the existing key that this object is working with by creating a new object. If `parameters` contains only the field, then only a public key is imported. If `parameters` also contains , then a full key pair is be imported. The `parameter` value specifies the type of the curve to import. + ]]> diff --git a/xml/System.Security.Cryptography/SP800108HmacCounterKdf.xml b/xml/System.Security.Cryptography/SP800108HmacCounterKdf.xml index 29a434f3bcb..a186b25bd91 100644 --- a/xml/System.Security.Cryptography/SP800108HmacCounterKdf.xml +++ b/xml/System.Security.Cryptography/SP800108HmacCounterKdf.xml @@ -83,7 +83,7 @@ To be added. - has a which is . + has a that's . -or- @@ -91,7 +91,7 @@ - has a which is empty. + has a that's empty. is not a known or supported hash algorithm. @@ -134,10 +134,10 @@ To be added. - has a which is . + has a that's . - has a which is empty. + has a that's empty. is not a known or supported hash algorithm. @@ -203,11 +203,11 @@ -or- - has a which is . + has a that's . - has a which is empty. + has a that's empty. is negative or larger than the maximum number of bytes @@ -263,8 +263,7 @@
An array containing the derived key. - and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + and will be converted to bytes using the UTF-8 encoding. For other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. @@ -281,11 +280,11 @@ -or- - has a which is . + has a that's . - has a which is empty. + has a that's empty. is negative or larger than the maximum number of bytes @@ -351,10 +350,10 @@ An array containing the derived key. To be added. - has a which is . + has a that's . - has a which is empty. + has a that's empty. is negative or larger than the maximum number of bytes @@ -410,10 +409,10 @@ To be added. - has a which is . + has a that's . - has a which is empty. + has a that's empty. is larger than the maximum number of bytes that can be derived. @@ -475,14 +474,14 @@ An array containing the derived key. and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + for other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. - has a which is . + has a that's . - has a which is empty. + has a that's empty. is negative or larger than the maximum number of bytes @@ -541,14 +540,14 @@ and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + for other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. - has a which is . + has a that's . - has a which is empty. + has a that's empty. is larger than the maximum number of bytes that can be derived. @@ -763,7 +762,7 @@ An array containing the derived key. and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + for other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. @@ -813,7 +812,7 @@ and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + for other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. @@ -863,7 +862,7 @@ An array containing the derived key. and will be converted to bytes using the UTF-8 encoding. - for other encodings, perform the conversion using the desired encoding and use an overload which accepts the + for other encodings, perform the conversion using the desired encoding and use an overload that accepts the label and context as a sequence of bytes. diff --git a/xml/System.Security.Cryptography/Shake128.xml b/xml/System.Security.Cryptography/Shake128.xml index 67b6388b3fa..3197c79859d 100644 --- a/xml/System.Security.Cryptography/Shake128.xml +++ b/xml/System.Security.Cryptography/Shake128.xml @@ -21,7 +21,7 @@ Computes the SHAKE128 hash for the input data. - This algorithm is specified by FIPS 202. The SHAKE algorithm family is an extendable-output function (XOF) which allows the output to be extended to any length. The size of the XOF indicates the security strength of the algorithm, not the output size. + This algorithm is specified by FIPS 202. The SHAKE algorithm family is an extendable-output function (XOF) that allows the output to be extended to any length. The size of the XOF indicates the security strength of the algorithm, not the output size. diff --git a/xml/System.Security.Cryptography/Shake256.xml b/xml/System.Security.Cryptography/Shake256.xml index fd43cc89f74..f311d6f1b4f 100644 --- a/xml/System.Security.Cryptography/Shake256.xml +++ b/xml/System.Security.Cryptography/Shake256.xml @@ -21,7 +21,7 @@ Computes the SHAKE256 hash for the input data. - This algorithm is specified by FIPS 202. The SHAKE algorithm family is an extendable-output function (XOF) which allows the output to be extended to any length. The size of the XOF indicates the security strength of the algorithm, not the output size. + This algorithm is specified by FIPS 202. The SHAKE algorithm family is an extendable-output function (XOF) that allows the output to be extended to any length. The size of the XOF indicates the security strength of the algorithm, not the output size. diff --git a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml index c294196d6cf..c2b05faf7e3 100644 --- a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml +++ b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml @@ -49,29 +49,29 @@ Defines the identity permission for strong names. This class cannot be inherited. - [!IMPORTANT] -> Starting with the .NET Framework 4, identity permissions are not used. -> -> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. In the .NET Framework version 2.0 and later, identity permissions can have any permission state value. This means that in version 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. - - Use to confirm that the calling code is in a particular strong-named code assembly. Full demands for succeed only if all the assemblies in the stack have the correct evidence to satisfy the demand. Link demands that use the attribute succeed only if the immediate caller has the correct evidence. - - A strong name identity is based on a cryptographic public key called a binary large object (BLOB), which is optionally combined with the name and version of a specific assembly. The key defines a unique namespace and provides strong verification that the name is genuine, because the definition of the name must be in an assembly that is signed by the corresponding private key. - - Note that the validity of the strong name key is not dependent on a trust relationship or on any certificate necessarily being issued for the key. - - In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective even when the calling assembly is fully trusted. That is, even if the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. In the .NET Framework version 2.0 and later, demands for identity permissions are ineffective if the calling assembly has full trust. This ensures consistency for all permissions and eliminates the treatment of identity permissions as a special case. - - For a complete description of strong names, see the reference page. For more information about strong-named assemblies, see [Strong-named assemblies](/dotnet/standard/assembly/strong-named). - - The class is used to define strong-name requirements for accessing the public members of a type. The attribute can be used to define strong-name requirements at the assembly level. In the .NET Framework version 2.0 and later, you can also use the attribute to specify that all nonpublic types in that assembly are visible to another assembly. For more information, see [Friend assemblies](/dotnet/standard/assembly/friend). - +> Starting with the .NET Framework 4, identity permissions are not used. +> +> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. In the .NET Framework version 2.0 and later, identity permissions can have any permission state value. This means that in version 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. + + Use to confirm that the calling code is in a particular strong-named code assembly. Full demands for succeed only if all the assemblies in the stack have the correct evidence to satisfy the demand. Link demands that use the attribute succeed only if the immediate caller has the correct evidence. + + A strong name identity is based on a cryptographic public key called a binary large object (BLOB), which is optionally combined with the name and version of a specific assembly. The key defines a unique namespace and provides strong verification that the name is genuine, because the definition of the name must be in an assembly that is signed by the corresponding private key. + + Note that the validity of the strong name key is not dependent on a trust relationship or on any certificate necessarily being issued for the key. + + In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective even when the calling assembly is fully trusted. That is, even if the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. In the .NET Framework version 2.0 and later, demands for identity permissions are ineffective if the calling assembly has full trust. This ensures consistency for all permissions and eliminates the treatment of identity permissions as a special case. + + For a complete description of strong names, see the reference page. For more information about strong-named assemblies, see [Strong-named assemblies](/dotnet/standard/assembly/strong-named). + + The class is used to define strong-name requirements for accessing the public members of a type. The attribute can be used to define strong-name requirements at the assembly level. In the .NET Framework version 2.0 and later, you can also use the attribute to specify that all nonpublic types in that assembly are visible to another assembly. For more information, see [Friend assemblies](/dotnet/standard/assembly/friend). + ]]> @@ -125,27 +125,27 @@ One of the values. Initializes a new instance of the class with the specified . - [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. In the .NET Framework version 2.0 and later, identity permissions can have any permission state value. This means that in version 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. - - In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. In the .NET Framework version 2.0 and later, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. - - Use this constructor with a permission state value of to create an identity permission that matches no strong names. If you subsequently set the and properties, a specific strong name identity can be represented by the permission. - - - -## Examples - The following code example shows the use of the constructor. - +> In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. In the .NET Framework version 2.0 and later, identity permissions can have any permission state value. This means that in version 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. That is, a demand for an identity always succeeds, regardless of the identity of the assembly, if the assembly has been granted full trust. + + In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. In the .NET Framework version 2.0 and later, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. + + Use this constructor with a permission state value of to create an identity permission that matches no strong names. If you subsequently set the and properties, a specific strong name identity can be represented by the permission. + + + +## Examples + The following code example shows the use of the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet7"::: + ]]> The parameter is not a valid value of . @@ -188,22 +188,22 @@ The version number of the identity. Initializes a new instance of the class for the specified strong name identity. - is thrown. - - For more information on names and version numbers of assemblies, see [Strong-named assemblies](/dotnet/standard/assembly/strong-named). - - - -## Examples - The following code example shows the use of the constructor. - + is thrown. + + For more information on names and version numbers of assemblies, see [Strong-named assemblies](/dotnet/standard/assembly/strong-named). + + + +## Examples + The following code example shows the use of the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet8"::: + ]]> The parameter is . @@ -244,23 +244,23 @@ Creates and returns an identical copy of the current permission. A copy of the current permission. - method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. - + method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet5"::: + ]]> @@ -301,30 +301,30 @@ The XML encoding to use to reconstruct the permission. Reconstructs a permission with a specified state from an XML encoding. - method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. - + method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet6"::: + ]]> The parameter is . - The parameter is not a valid permission element. - - -or- - + The parameter is not a valid permission element. + + -or- + The parameter's version number is not valid. @@ -365,25 +365,25 @@ Creates and returns a permission that is the intersection of the current permission and the specified permission. A new permission that represents the intersection of the current permission and the specified permission, or if the intersection is empty. - method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. - + method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet4"::: + ]]> The parameter is not and is not of the same type as the current permission. @@ -427,23 +427,23 @@ if the current permission is a subset of the specified permission; otherwise, . - property containing the wildcard expression MyCompany.MyDepartment.* is identified as a subset of an identity with the property MyCompany.MyDepartment.MyFile. - - - -## Examples - The following code example shows the results of the use of the method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. - + property containing the wildcard expression MyCompany.MyDepartment.* is identified as a subset of an identity with the property MyCompany.MyDepartment.MyFile. + + + +## Examples + The following code example shows the results of the use of the method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet2"::: + ]]> The parameter is not and is not of the same type as the current permission. @@ -482,11 +482,11 @@ Gets or sets the simple name portion of the strong name identity. The simple name of the identity. - property can be an exact name or can be modified by a wildcard character in the final position; for example, both MyCompany.MyDepartment.MyFile and MyCompany.MyDepartment.* are valid names. If you attempt to set the property to an empty string (""), an is thrown. - + property can be an exact name or can be modified by a wildcard character in the final position; for example, both MyCompany.MyDepartment.MyFile and MyCompany.MyDepartment.* are valid names. If you attempt to set the property to an empty string (""), an is thrown. + ]]> The value is an empty string (""). @@ -564,23 +564,23 @@ Creates an XML encoding of the permission and its current state. An XML encoding of the permission, including any state information. - method. - + method. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet6"::: + ]]> @@ -622,31 +622,31 @@ Creates a permission that is the union of the current permission and the specified permission. A new permission that represents the union of the current permission and the specified permission. - is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - - The union of a permission and `null` is the permission that is not `null`. The union of a permission and a subset of that permission is the permission that contains the other. Any other combination results in an exception being thrown. - - - -## Examples - The following code example shows the results of the use of the method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. - + is a permission that represents all the operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + + The union of a permission and `null` is the permission that is not `null`. The union of a permission and a subset of that permission is the permission that contains the other. Any other combination results in an exception being thrown. + + + +## Examples + The following code example shows the results of the use of the method, not how to use the method. This example is part of a larger example provided for the class. The best use for this example is to build and execute the entire example, and view its output. + > [!NOTE] -> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. - +> The code example is intended to show the behavior of the method, not to demonstrate its use. In general, the methods of permission classes are used by the security infrastructure; they are not typically used in applications. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/CPP/strongnameidentity.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Permissions/StrongNameIdentityPermission/.ctor/strongnameidentity.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.StrongNameIdentityPermission/VB/strongnameidentity.vb" id="Snippet3"::: + ]]> - The parameter is not and is not of the same type as the current permission. - - -or- - + The parameter is not and is not of the same type as the current permission. + + -or- + The two permissions are not equal and one is a subset of the other. diff --git a/xml/System.Security.RightsManagement/ContentGrant.xml b/xml/System.Security.RightsManagement/ContentGrant.xml index c31e4ccf852..393b487fa47 100644 --- a/xml/System.Security.RightsManagement/ContentGrant.xml +++ b/xml/System.Security.RightsManagement/ContentGrant.xml @@ -29,11 +29,11 @@ Represents a right granted to a user to access information in a rights managed document. - types, is only usable in full trust applications. - + types, is only usable in full trust applications. + ]]> @@ -79,17 +79,17 @@ The access right that is granted. Initializes a new instance of the class that grants a specified a specified . - instance with no date or time limitations. - -- The property is set to . which indicates there is no starting limitation. - -- The property is set to . which indicates there is no ending limitation. - - Use the alternate constructor to create an instance with date and time limitations. - + instance with no date or time limitations. + +- The property is set to ., which indicates there is no starting limitation. + +- The property is set to ., which indicates there is no ending limitation. + + Use the alternate constructor to create an instance with date and time limitations. + ]]> @@ -130,13 +130,13 @@ The ending date and time that the right expires. Initializes a new instance of the class that grants a specified a specified for a specified duration. - . if there is no start date and time limitation. - - Specify the `validUntil` parameter with . if there is no end date and time limitation. - + . if there is no start date and time limitation. + + Specify the `validUntil` parameter with . if there is no end date and time limitation. + ]]> diff --git a/xml/System.ServiceProcess/ServiceBase.xml b/xml/System.ServiceProcess/ServiceBase.xml index de5041a0786..57548927eda 100644 --- a/xml/System.ServiceProcess/ServiceBase.xml +++ b/xml/System.ServiceProcess/ServiceBase.xml @@ -1097,7 +1097,7 @@ - A which indicates a service to start. + A that indicates a service to start. Registers the executable for a service with the Service Control Manager (SCM). 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.Text.Json.Serialization.Metadata/JsonParameterInfo.xml b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfo.xml index d6023464fbd..87a6b9cb5ac 100644 --- a/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfo.xml +++ b/xml/System.Text.Json.Serialization.Metadata/JsonParameterInfo.xml @@ -148,7 +148,7 @@ Gets a value indicating whether the parameter represents a required or init-only member initializer. To be added. - Only returns for source generated metadata which can only access + Only returns for source-generated metadata that can only access required or init-only member initializers using object initialize expressions. diff --git a/xml/System.Text.Json/JsonSerializer.xml b/xml/System.Text.Json/JsonSerializer.xml index 800a822fe9a..a94a915f4ff 100644 --- a/xml/System.Text.Json/JsonSerializer.xml +++ b/xml/System.Text.Json/JsonSerializer.xml @@ -2749,7 +2749,7 @@ There is remaining data in the stream. The type to deserialize the JSON value into. JSON data to parse. Metadata about the type to convert. - The which may be used to cancel the read operation. + The that can be used to cancel the read operation. Reads the UTF-8 encoded text representing a single JSON value into a . The Stream will be read to completion. A representation of the JSON value. @@ -2814,7 +2814,7 @@ There is remaining data in the stream. The element type to deserialize asynchronously. JSON data to parse. Options to control the behavior during reading. - The which may be used to cancel the read operation. + The that can be used to cancel the read operation. Wraps the UTF-8 encoded text into an that can be used to deserialize root-level JSON arrays in a streaming manner. An representation of the provided JSON array. To be added. diff --git a/xml/System.Text/CodePagesEncodingProvider.xml b/xml/System.Text/CodePagesEncodingProvider.xml index 72ee77025bd..149ac295a93 100644 --- a/xml/System.Text/CodePagesEncodingProvider.xml +++ b/xml/System.Text/CodePagesEncodingProvider.xml @@ -151,7 +151,7 @@ The .NET Framework supports a large number of character encodings and code pages - The code page identifier of the preferred encoding which the encoding provider may support. + The code page identifier of the preferred encoding that the encoding provider might support. Returns the encoding associated with the specified code page identifier. The encoding associated with the specified code page identifier, or if the provider does not support the requested codepage encoding. To be added. @@ -190,7 +190,7 @@ The .NET Framework supports a large number of character encodings and code pages - The code page name of the preferred encoding which the encoding provider may support. + The code page name of the preferred encoding that the encoding provider might support. Returns the encoding associated with the specified code page name. The encoding associated with the specified code page, or if the provider does not support the requested encoding. To be added. diff --git a/xml/System.Text/EncodingExtensions.xml b/xml/System.Text/EncodingExtensions.xml index 2451cf72144..21df242bd09 100644 --- a/xml/System.Text/EncodingExtensions.xml +++ b/xml/System.Text/EncodingExtensions.xml @@ -604,7 +604,7 @@ The encoding that represents how the data in is encoded. The sequence to decode into characters. Decodes the specified into a using the specified . - A which represents the decoded contents of . + The decoded contents of . To be added. contains data that cannot be decoded and is configured to throw when such data is seen. 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.Web.SessionState/SessionStateUtility.xml b/xml/System.Web.SessionState/SessionStateUtility.xml index 27d3625ade2..bbb0b3b931e 100644 --- a/xml/System.Web.SessionState/SessionStateUtility.xml +++ b/xml/System.Web.SessionState/SessionStateUtility.xml @@ -212,7 +212,7 @@ Specifies the to check. - Gets a value which indicates whether the session state is read-only for the specified . + Gets a value that indicates whether the session state is read-only for the specified . if the session state is read-only; otherwise, . To be added. @@ -238,7 +238,7 @@ Specifies the to check. - Gets a value which indicates whether the session state is required for the specified . + Gets a value that indicates whether the session state is required for the specified . if the session state is required; otherwise, . To be added. diff --git a/xml/System.Windows/Application.xml b/xml/System.Windows/Application.xml index 47b9ad209f8..66370d1f13c 100644 --- a/xml/System.Windows/Application.xml +++ b/xml/System.Windows/Application.xml @@ -1747,14 +1747,12 @@ For more information about XBAP support, see [Frequently asked questions about W exposes a dictionary via which you can use to store application-scope properties. This allows you to share state amongst all code in an in a thread-safe fashion, without the need to write your own state code. + exposes a dictionary via that you can use to store application-scope properties. This allows you to share state amongst all code in an in a thread-safe fashion, without the need to write your own state code. Properties stored in must be converted to the appropriate type returned. The property is thread safe and is available from any thread. - - ## Examples The following example shows how create and use an application-scope property using . diff --git a/xml/System.Windows/CornerRadiusConverter.xml b/xml/System.Windows/CornerRadiusConverter.xml index 8480f013e22..6776abbef9b 100644 --- a/xml/System.Windows/CornerRadiusConverter.xml +++ b/xml/System.Windows/CornerRadiusConverter.xml @@ -166,7 +166,7 @@ is . - is not and is not a valid type which can be converted to a . + is not and is not a valid type that can be converted to a . @@ -212,11 +212,11 @@ Converts the specified to the specified type. The object created from converting this (a string). - . - + . + ]]> diff --git a/xml/System.Windows/FigureUnitType.xml b/xml/System.Windows/FigureUnitType.xml index 238bf4348b9..a1197318c5b 100644 --- a/xml/System.Windows/FigureUnitType.xml +++ b/xml/System.Windows/FigureUnitType.xml @@ -22,17 +22,17 @@ Describes the unit type associated with the width or height of a . - , the of the decreases. Below is the XAML for the sample. - - :::code language="xaml" source="~/snippets/csharp/System.Windows/BaselineAlignment/Overview/figurelengthexample.xaml" id="Snippetfigurelengthexamplewholepage"::: - - Below is the code used to decrease the of the using the Pixel to specify the unit type. - - :::code language="csharp" source="~/snippets/csharp/System.Windows/BaselineAlignment/Overview/figurelengthexample.xaml.cs" id="Snippetfigurelengthcodebehindexamplewholepage"::: - + , the of the decreases. Below is the XAML for the sample. + + :::code language="xaml" source="~/snippets/csharp/System.Windows/BaselineAlignment/Overview/figurelengthexample.xaml" id="Snippetfigurelengthexamplewholepage"::: + + Below is the code used to decrease the of the using the Pixel to specify the unit type. + + :::code language="csharp" source="~/snippets/csharp/System.Windows/BaselineAlignment/Overview/figurelengthexample.xaml.cs" id="Snippetfigurelengthcodebehindexamplewholepage"::: + ]]> @@ -61,7 +61,7 @@ 0 - Default value when the is not specified which creates a value for the width or height of the that is calculated without constraints. **Note:** When is set to , the property of is set to 1. + Default value when the is not specified that creates a value for the width or height of the that is calculated without constraints. **Note:** When is set to , the property of is set to 1. diff --git a/xml/System.Windows/FontSizeConverter.xml b/xml/System.Windows/FontSizeConverter.xml index 27c7dbc8337..07b2963b520 100644 --- a/xml/System.Windows/FontSizeConverter.xml +++ b/xml/System.Windows/FontSizeConverter.xml @@ -23,11 +23,11 @@ Converts font size values to and from other type representations. - object supports conversion to and from the following types: include , , , and . There is no actual `FontSize` type, but values for font sizes are generally typed as , so the converter's destination type is . - + object supports conversion to and from the following types: include , , , and . There is no actual `FontSize` type, but values for font sizes are generally typed as , so the converter's destination type is . + ]]> @@ -165,7 +165,7 @@ Context information of a component such as its container and . Cultural specific information, including the writing system and calendar used. - The value which is being converted to a font size value. + The value that is being converted to a font size value. Converts a specified type to a . A value that represents the converted font size value. To be added. diff --git a/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilerParameters.xml b/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilerParameters.xml index 6efeeeb0c44..09c2f0e908e 100644 --- a/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilerParameters.xml +++ b/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilerParameters.xml @@ -27,21 +27,21 @@ Represents parameters passed to during the compilation process. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - - -## Examples - The following code example demonstrates how to create a new instance of the class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + + +## Examples + The following code example demonstrates how to create a new instance of the class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wf_samples/cs/snippets1.cs" id="Snippet99"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: + ]]> @@ -93,14 +93,14 @@ The names of the assemblies used in compilation. Initializes a new instance of the class, with the names of the assemblies used in compilation. - class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). - + class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wf_samples/cs/snippets1.cs" id="Snippet99"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: + ]]> @@ -215,7 +215,7 @@ System.Boolean - Gets or sets a value which indicates whether to generate only a , or to call the C# or Visual Basic compiler to generate the executable or DLL. + Gets or sets a value that indicates whether to generate only a , or to call the C# or Visual Basic compiler to generate the executable or DLL. A value which indicates whether to generate only a , or to call the C# or Visual Basic compiler to generate the executable or DLL. To be added. @@ -262,19 +262,19 @@ Gets the property that represents a collection of directory names under which compiler looks for referenced assemblies. The property that represents a collection of directory names under which compiler looks for referenced assemblies. - class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). - + class, add and set the value for the property. The code also creates a new instance of the class and runs the method. This code assumes that `results` is of type . This code example is part of the Outlook Workflow Wizard SDK Sample from the WizardForm.cs file. For more information, see [Outlook Workflow Wizard](https://learn.microsoft.com/previous-versions/dotnet/netframework-3.5/ms741721(v=vs.90)). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wf_samples/cs/snippets1.cs" id="Snippet99"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/wf_samples/vb/snippets1.vb" id="Snippet99"::: + ]]> 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. diff --git a/xml/System/AggregateException.xml b/xml/System/AggregateException.xml index 7f3cda79a7e..c8ade762787 100644 --- a/xml/System/AggregateException.xml +++ b/xml/System/AggregateException.xml @@ -808,7 +808,7 @@ was handled. After all invocations, if any exceptions went unhandled, all unhandled exceptions will be put into a new which will be thrown. Otherwise, the method simply returns. If any invocations of the `predicate` throws an exception, it will halt the processing of any more exceptions and immediately propagate the thrown exception as-is. + Each invocation of the `predicate` returns true or false to indicate whether the was handled. After all invocations, any unhandled exceptions are put into a new that will be thrown. If there are no unhandled exceptions, the method simply returns. If any invocations of the `predicate` throws an exception, it will halt the processing of any more exceptions and immediately propagate the thrown exception as-is. ## Examples Ordinarily, an exception handler that catches an exception uses a `foreach` loop (in C#) or `For Each` loop (in Visual Basic) to handle each exception in its collection. Instead, the following example uses the method to handle each exception, and only rethrows exceptions that are not `CustomException` instances. diff --git a/xml/System/Byte.xml b/xml/System/Byte.xml index c9d9e4f2492..6ead0efb039 100644 --- a/xml/System/Byte.xml +++ b/xml/System/Byte.xml @@ -700,8 +700,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2143,7 +2143,7 @@ For , this method matches the IEEE 754: - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2183,7 +2183,7 @@ For , this method matches the IEEE 754: - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/CharEnumerator.xml b/xml/System/CharEnumerator.xml index 4fb2339c1ee..1709d852659 100644 --- a/xml/System/CharEnumerator.xml +++ b/xml/System/CharEnumerator.xml @@ -76,40 +76,40 @@ Supports iterating over a object and reading its individual characters. This class cannot be inherited. - provides read-only access to the characters in a referenced object. For example, the `foreach` statement of the Microsoft Visual Basic and C# programming languages, which iterates through the elements of a collection, retrieves a from a object in order to iterate through the characters in that object. + provides read-only access to the characters in a referenced object. For example, the `foreach` statement of the Microsoft Visual Basic and C# programming languages, which iterates through the elements of a collection, retrieves a from a object in order to iterate through the characters in that object. > [!IMPORTANT] > The `CharEnumerator` class enumerates individual 16-bit instances. It does not consider graphemes (that is, a character followed by one or more combiding characters) or surrogate pairs (that is, characters outside the Unicode Basic Multilingual Plane) as single characters. For an enumerator that handles these types of characters as a single unit, use the class. - There is no public constructor for . Instead, call a object's method to obtain a that is initialized to reference the string. - - A maintains an internal index to the characters in the string the references. The state of the index is invalid when it references a character position logically before the first character or after the last character in the string, and valid when it references a character within the string. The index is initialized to a position logically before the first character, and is set to a position after the last character when the iteration is complete. An exception is thrown if you attempt to access a character while the index is invalid. - - The method increments the index by one, so the first and subsequent characters are accessed in turn. The method sets the index to a position logically before the first character. The property retrieves the character currently referenced by index. The method creates a copy of the . - + There is no public constructor for . Instead, call a object's method to obtain a that is initialized to reference the string. + + A maintains an internal index to the characters in the string the references. The state of the index is invalid when it references a character position logically before the first character or after the last character in the string, and valid when it references a character within the string. The index is initialized to a position logically before the first character, and is set to a position after the last character when the iteration is complete. An exception is thrown if you attempt to access a character while the index is invalid. + + The method increments the index by one, so the first and subsequent characters are accessed in turn. The method sets the index to a position logically before the first character. The property retrieves the character currently referenced by index. The method creates a copy of the . + > [!NOTE] -> Several independent instances of across one or more threads can have access to a single instance of . This class is implemented to support the interface. For more information regarding the use of an enumerator, see the topic. - - - -## Examples - The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. - +> Several independent instances of across one or more threads can have access to a single instance of . This class is implemented to support the interface. For more information regarding the use of an enumerator, see the topic. + + + +## Examples + The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: - - Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: + + Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: + ]]> @@ -167,18 +167,18 @@ Creates a copy of the current object. An that is a copy of the current object. - and its current state. This is useful for saving your state while iterating through a object. - - For example, suppose your application uses an original instance of to iterate through each character in a . When some unique character is encountered, your application pauses processing and invokes the method. In effect, this saves the object's index in the . - - Your application uses the clone to navigate to another part of the `String` to perform some auxiliary processing. The side-effect of this navigation is the clone loses track of the position where processing stopped. However, when the auxiliary processing is complete, your application discards the clone and uses the original instance to resume working on the where the original processing stopped. - + and its current state. This is useful for saving your state while iterating through a object. + + For example, suppose your application uses an original instance of to iterate through each character in a . When some unique character is encountered, your application pauses processing and invokes the method. In effect, this saves the object's index in the . + + Your application uses the clone to navigate to another part of the `String` to perform some auxiliary processing. The side-effect of this navigation is the clone loses track of the position where processing stopped. However, when the auxiliary processing is complete, your application discards the clone and uses the original instance to resume working on the where the original processing stopped. + > [!NOTE] -> This method is implemented to support the interface. - +> This method is implemented to support the interface. + ]]> @@ -225,32 +225,32 @@ Gets the currently referenced character in the string enumerated by this object. The Unicode character currently referenced by this object. - class maintains an internal index to the enumerated string, and the property returns the character that is currently referenced by the index. This property should be invoked only when the index is valid; otherwise, an exception is thrown. - - The index is always invalid for an empty string (""). The index is also invalid after the or method is called. After either of these methods is called, invoke the method to adjust the index to the first character in the enumerated string. The index is valid whenever the method returns `true`. - - does not move the index, and consecutive calls to return the same character until , , or is called. - - - -## Examples - The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. - + class maintains an internal index to the enumerated string, and the property returns the character that is currently referenced by the index. This property should be invoked only when the index is valid; otherwise, an exception is thrown. + + The index is always invalid for an empty string (""). The index is also invalid after the or method is called. After either of these methods is called, invoke the method to adjust the index to the first character in the enumerated string. The index is valid whenever the method returns `true`. + + does not move the index, and consecutive calls to return the same character until , , or is called. + + + +## Examples + The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: - - Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: + + Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: + ]]> The index is invalid; that is, it is before the first or after the last character of the enumerated string. @@ -296,16 +296,16 @@ Releases all resources used by the current instance of the class. - when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. - +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. + ]]> @@ -354,32 +354,30 @@ if the index is successfully incremented and within the enumerated string; otherwise, . - class maintains an internal index to the enumerated string, and the method increments the index by one. Call after calling or to increment the current character position to the first character in the enumerated string. Check that the return value is `true` to determine that the current character position is valid. - - If the index is already beyond the last character of the enumerated string, the index is not changed and `false` is returned. - - Notice that if the enumerated string is empty (""), the state of the is always invalid. This is because the internal index for the is initially before the first character of the enumerated string and is therefore invalid. logically sets the index after the last (nonexistent) character of the enumerated string which is also invalid. - - - -## Examples - The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. - + class maintains an internal index to the enumerated string, and the method increments the index by one. Call after calling or to increment the current character position to the first character in the enumerated string. Check that the return value is `true` to determine that the current character position is valid. + + If the index is already beyond the last character of the enumerated string, the index is not changed and `false` is returned. + + Notice that if the enumerated string is empty (""), the state of the is always invalid. This is because the internal index for the is initially before the first character of the enumerated string and is therefore invalid. logically sets the index after the last (nonexistent) character of the enumerated string, which is also invalid. + +## Examples + The following example uses the class to enumerate the individual characters in a string. It instantiates a object by calling the method, moves from one character to the next by calling the method, and displays the current character by retrieving the value of the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: - - Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet1"::: + + Note, however, that the same operation can be performed somewhat more intuitively by using `foreach` (in C#) or `For Each` (in Visual Basic), as the following example shows. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.CharEnumerator.Class/cpp/charenumerator1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/CharEnumerator/Overview/CharEnumerator1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.CharEnumerator.Class/fs/CharEnumerator1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.CharEnumerator.Class/vb/CharEnumerator1.vb" id="Snippet2"::: + ]]> @@ -426,11 +424,11 @@ Initializes the index to a position logically before the first character of the enumerated string. - class maintains an internal index to the enumerated string, and the method sets the index to the invalid state. - + class maintains an internal index to the enumerated string, and the method sets the index to the invalid state. + ]]> @@ -484,17 +482,17 @@ Gets the currently referenced character in the string enumerated by this object. For a description of this member, see . The boxed Unicode character currently referenced by this object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> - Enumeration has not started. - - -or- - + Enumeration has not started. + + -or- + Enumeration has ended. @@ -528,7 +526,7 @@ class. The method leaves the class in an unusable state. After calling it, you must release all references to the class so the garbage collector can reclaim the memory that the class was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). diff --git a/xml/System/ContextMarshalException.xml b/xml/System/ContextMarshalException.xml index 96375ac616d..4718ae68505 100644 --- a/xml/System/ContextMarshalException.xml +++ b/xml/System/ContextMarshalException.xml @@ -72,17 +72,17 @@ The exception that is thrown when an attempt to marshal an object across a context boundary fails. - . - - uses the HRESULT COR_E_CONTEXTMARSHAL which has the value 0x80131504L. - - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of , see the constructors. - + . + + uses the HRESULT COR_E_CONTEXTMARSHAL, which has the value 0x80131504L. + + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -137,16 +137,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The empty string ("").| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The empty string ("").| + ]]> @@ -194,16 +194,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -313,18 +313,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/DateTime.xml b/xml/System/DateTime.xml index d7f38a56994..d32f7cd66f9 100644 --- a/xml/System/DateTime.xml +++ b/xml/System/DateTime.xml @@ -8087,7 +8087,7 @@ In general, the ticks represent the time according to the time zone specified by property. which returns a value that represents a date without its time component, the property returns a value that represents a value's time component. + Unlike the property, which returns a value that represents a date without its time component, the property returns a value that represents a value's time component. If you want to display the time of day or retrieve the string representation of the time of day of a value, you can instead call an overload of the method that has a `format` parameter or use the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature with the "t" or "T" standard format string. @@ -8271,9 +8271,7 @@ In general, the ticks represent the time according to the time zone specified by ## Remarks A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file. - The method uses the property to determine whether the current object is a local time, a UTC time, or an unspecified kind of time which is treated as a local time. - - + The method uses the property to determine whether the current object is a local time, a UTC time, or an unspecified kind of time, which is treated as a local time. ## Examples The following example demonstrates the method. @@ -8354,7 +8352,7 @@ In general, the ticks represent the time according to the time zone specified by ## Remarks A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file. - The method uses the property to determine whether the current object is a local time, a UTC time, or an unspecified kind of time which is treated as a UTC time. If it is a local time, it converts the time to UTC before performing the conversion to a Windows file time. + The method uses the property to determine whether the current object is a local time, a UTC time, or an unspecified kind of time, which is treated as a UTC time. If it is a local time, it converts the time to UTC before performing the conversion to a Windows file time. ]]> diff --git a/xml/System/Double.xml b/xml/System/Double.xml index dbf37567645..293b2c4162a 100644 --- a/xml/System/Double.xml +++ b/xml/System/Double.xml @@ -2257,8 +2257,8 @@ Euler's number is approximately 2.7182818284590452354. - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . The value that is added to the product of and . Computes the fused multiply-add of three values. The result of times plus computed as one ternary operation. @@ -2436,8 +2436,8 @@ Euler's number is approximately 2.7182818284590452354. - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the remainder of two values as specified by IEEE 754. The remainder of divided-by as specified by IEEE 754. To be added. @@ -5643,7 +5643,7 @@ The following code example illustrates the use of - The value which is raised to the power of . + The value that is raised to the power of . The power to which is raised. Computes a value raised to a given power. @@ -5997,7 +5997,7 @@ The following code example illustrates the use of - The value which base-radix raised to the power of multiplies. + The value that base-radix raised to the power of multiplies. The value to which base-radix is raised before multipliying . Computes the product of a value and its base-radix raised to the specified power. The product of and base-radix raised to the power of . diff --git a/xml/System/Guid.xml b/xml/System/Guid.xml index f35e4914c8d..0a122a61ed4 100644 --- a/xml/System/Guid.xml +++ b/xml/System/Guid.xml @@ -1180,7 +1180,7 @@ On non-Windows platforms, starting with .NET 6, this function calls the OS's underlying cryptographically secure pseudo-random number generator (CSPRNG) to generate 122 bits of strong entropy. In previous versions of .NET, the entropy is not guaranteed to be generated by a CSPRNG. - It is recommended that applications __not__ use the _NewGuid_ method for cryptographic purposes. First, since a Version 4 UUID has a partially predictable bit pattern, the _NewGuid_ function cannot serve as a proper cryptographic pseudo-random function (PRF). If the output of _NewGuid_ is given to a cryptographic component which requires its input to be generated by a proper PRF, the cryptographic component may not be able to maintain its security properties. Second, _NewGuid_ utilizes at most 122 bits of entropy, regardless of platform. Some cryptographic components set a minimum entropy level on their inputs as a matter of policy. Such policies often set the minimum entropy level at 128 bits or higher. Passing the output of _NewGuid_ to such a routine may violate its policy. + It is recommended that applications __not__ use the _NewGuid_ method for cryptographic purposes. First, since a Version 4 UUID has a partially predictable bit pattern, the _NewGuid_ function cannot serve as a proper cryptographic pseudo-random function (PRF). If the output of _NewGuid_ is given to a cryptographic component that requires its input to be generated by a proper PRF, the cryptographic component may not be able to maintain its security properties. Second, _NewGuid_ utilizes at most 122 bits of entropy, regardless of platform. Some cryptographic components set a minimum entropy level on their inputs as a matter of policy. Such policies often set the minimum entropy level at 128 bits or higher. Passing the output of _NewGuid_ to such a routine may violate its policy. If an application requires random data for cryptographic purposes, consider using a static method on the class. That class provides a random number generator suitable for cryptographic use. diff --git a/xml/System/Half.xml b/xml/System/Half.xml index 30c7694f61e..67f2c3d18a4 100644 --- a/xml/System/Half.xml +++ b/xml/System/Half.xml @@ -1315,7 +1315,7 @@ This computes `cos(x * π)`. The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -1361,7 +1361,7 @@ This computes `cos(x * π)`. The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -1791,8 +1791,8 @@ This computes `cos(x * π)`. - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . The value that is added to the product of and . Computes the fused multiply-add of three values. The result of times plus computed as one ternary operation. @@ -1887,8 +1887,8 @@ This computes `cos(x * π)`. - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the remainder of two values as specified by IEEE 754. The remainder of divided-by as specified by IEEE 754. To be added. @@ -3417,7 +3417,7 @@ For this method matches the IEEE 754:2 The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -3510,8 +3510,8 @@ For this method matches the IEEE 754:2 - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided-by . To be added. @@ -4744,8 +4744,8 @@ For this method matches the IEEE 754:2 - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their modulus or remainder. The modulus or remainder of divided-by . To be added. @@ -4778,8 +4778,8 @@ For this method matches the IEEE 754:2 - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied-by . To be added. @@ -4813,7 +4813,7 @@ For this method matches the IEEE 754:2 The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The difference of subtracted from . To be added. @@ -5328,7 +5328,7 @@ For this method matches the IEEE 754:2 - The value which is raised to the power of . + The value that is raised to the power of . The power to which is raised. Computes a value raised to a given power. @@ -5628,7 +5628,7 @@ For this method matches the IEEE 754:2 - The value which base-radix raised to the power of multiplies. + The value that base-radix raised to the power of multiplies. The value to which base-radix is raised before multipliying . Computes the product of a value and its base-radix raised to the specified power. The product of and base-radix raised to the power of . diff --git a/xml/System/Int128.xml b/xml/System/Int128.xml index 2991d58b598..f0b6f4ba8b7 100644 --- a/xml/System/Int128.xml +++ b/xml/System/Int128.xml @@ -519,7 +519,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -565,7 +565,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -604,8 +604,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -1284,7 +1284,7 @@ For this method matches the IEE The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -1386,7 +1386,7 @@ For this method matches the IEE The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -1451,8 +1451,8 @@ For this method matches the IEE - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided-by . To be added. @@ -1601,8 +1601,8 @@ For this method matches the IEE - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied-by . To be added. @@ -1636,7 +1636,7 @@ For this method matches the IEE The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The difference of subtracted from . To be added. @@ -1733,8 +1733,8 @@ For this method matches the IEE - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided-by . To be added. @@ -3013,8 +3013,8 @@ For this method matches the IEE - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their modulus or remainder. The modulus or remainder of divided-by . To be added. @@ -3047,8 +3047,8 @@ For this method matches the IEE - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied-by . To be added. @@ -3156,7 +3156,7 @@ This operation is meant to perform a signed (otherwise known as an arithmetic) r The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The difference of subtracted from . To be added. @@ -3630,7 +3630,7 @@ This operation is meant to perform n unsigned (otherwise known as a logical) rig - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -3664,7 +3664,7 @@ This operation is meant to perform n unsigned (otherwise known as a logical) rig - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/Int16.xml b/xml/System/Int16.xml index 9df301eb024..2cb4ead33e1 100644 --- a/xml/System/Int16.xml +++ b/xml/System/Int16.xml @@ -776,8 +776,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2408,7 +2408,7 @@ For this method matches the IEE - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2448,7 +2448,7 @@ For this method matches the IEE - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/Int32.xml b/xml/System/Int32.xml index dbe8345f4d7..940abb3035a 100644 --- a/xml/System/Int32.xml +++ b/xml/System/Int32.xml @@ -804,8 +804,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2471,7 +2471,7 @@ For this method matches the IEE - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2511,7 +2511,7 @@ For this method matches the IEE - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/Int64.xml b/xml/System/Int64.xml index 547fa606502..302bdc15cd7 100644 --- a/xml/System/Int64.xml +++ b/xml/System/Int64.xml @@ -798,8 +798,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2405,7 +2405,7 @@ For this method matches the IEE - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2445,7 +2445,7 @@ For this method matches the IEE - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/IntPtr.xml b/xml/System/IntPtr.xml index 49597e2da6d..1c2a467ba5d 100644 --- a/xml/System/IntPtr.xml +++ b/xml/System/IntPtr.xml @@ -905,7 +905,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -957,7 +957,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -1002,8 +1002,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2911,7 +2911,7 @@ For this method matches the IEE - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2951,7 +2951,7 @@ For this method matches the IEE - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/Math.xml b/xml/System/Math.xml index dd4d2addc04..027d3c2362d 100644 --- a/xml/System/Math.xml +++ b/xml/System/Math.xml @@ -3809,7 +3809,7 @@ Dim i2 As Integer = CInt(Math.Floor(d2)) ' Result: 7968 ## Remarks This computes `(x * y)` as if to infinite precision, adds `z` to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute `(x * y)` as if to infinite precision, round the result to the nearest representable value, add `z` to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, which would compute `(x * y)` as if to infinite precision, round the result to the nearest representable value, add `z` to the rounded result as if to infinite precision, and finally round to the nearest representable value. ]]> diff --git a/xml/System/MathF.xml b/xml/System/MathF.xml index 391b974c3ff..26c61d41316 100644 --- a/xml/System/MathF.xml +++ b/xml/System/MathF.xml @@ -1115,7 +1115,7 @@ The value of this constant is 2.71828175. ## Remarks This computes `(x * y)` as if to infinite precision, adds `z` to that result as if to infinite precision, and finally rounds to the nearest representable value. - This differs from the non-fused sequence which would compute `(x * y)` as if to infinite preicision, round the result to the nearest representable value, add 'z' to the rounded result as if to infinite precision, and finally round to the nearest representable value. + This differs from the non-fused sequence, which would compute `(x * y)` as if to infinite preicision, round the result to the nearest representable value, add 'z' to the rounded result as if to infinite precision, and finally round to the nearest representable value. ]]> diff --git a/xml/System/SByte.xml b/xml/System/SByte.xml index 6dd56884143..c4957fc90e5 100644 --- a/xml/System/SByte.xml +++ b/xml/System/SByte.xml @@ -781,8 +781,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2437,7 +2437,7 @@ For this method matches the IEE - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2477,7 +2477,7 @@ For this method matches the IEE - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/Single.xml b/xml/System/Single.xml index 009c6a22ce0..389a3b125ba 100644 --- a/xml/System/Single.xml +++ b/xml/System/Single.xml @@ -2270,8 +2270,8 @@ This is known as Euler's number and is approximately 2.7182818284590452354. - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . The value that is added to the product of and . Computes the fused multiply-add of three values. The result of times plus computed as one ternary operation. @@ -2449,8 +2449,8 @@ This is known as Euler's number and is approximately 2.7182818284590452354. - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the remainder of two values as specified by IEEE 754. The remainder of divided-by as specified by IEEE 754. To be added. @@ -5672,7 +5672,7 @@ Pi is approximately 3.1415926535897932385. - The value which is raised to the power of . + The value that is raised to the power of . The power to which is raised. Computes a value raised to a given power. @@ -6026,7 +6026,7 @@ Pi is approximately 3.1415926535897932385. - The value which base-radix raised to the power of multiplies. + The value that base-radix raised to the power of multiplies. The value to which base-radix is raised before multipliying . Computes the product of a value and its base-radix raised to the specified power. The product of and base-radix raised to the power of . diff --git a/xml/System/Type.xml b/xml/System/Type.xml index 6eb2fd35bc7..63043b2bc19 100644 --- a/xml/System/Type.xml +++ b/xml/System/Type.xml @@ -3424,7 +3424,7 @@ If the current represents a generic type parameter, the - The string containing the name of an event which is declared or inherited by the current . + The name of an event that is declared or inherited by the current . A bitwise combination of the enumeration values that specify how the search is conducted. -or- diff --git a/xml/System/UInt128.xml b/xml/System/UInt128.xml index d5867ae5626..ee70d100ae2 100644 --- a/xml/System/UInt128.xml +++ b/xml/System/UInt128.xml @@ -457,7 +457,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -503,7 +503,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -542,8 +542,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -1026,7 +1026,7 @@ For this method matches the IEEE 754:2 The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -1128,7 +1128,7 @@ For this method matches the IEEE 754:2 The value to which is added. - The value which is added to . + The value that is added to . Adds two values together to compute their sum. The sum of and . To be added. @@ -1193,8 +1193,8 @@ For this method matches the IEEE 754:2 - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided-by . To be added. @@ -1489,8 +1489,8 @@ For this method matches the IEEE 754:2 - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied-by . To be added. @@ -1524,7 +1524,7 @@ For this method matches the IEEE 754:2 The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The difference of subtracted from . To be added. @@ -1621,8 +1621,8 @@ For this method matches the IEEE 754:2 - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their quotient. The quotient of divided-by . To be added. @@ -2901,8 +2901,8 @@ For this method matches the IEEE 754:2 - The value which divides. - The value which divides . + The value that divides. + The value that divides . Divides two values together to compute their modulus or remainder. The modulus or remainder of divided-by . To be added. @@ -2935,8 +2935,8 @@ For this method matches the IEEE 754:2 - The value which multiplies. - The value which multiplies . + The value that multiplies. + The value that multiplies . Multiplies two values together to compute their product. The product of multiplied-by . To be added. @@ -3044,7 +3044,7 @@ This operation is meant to perform a signed (otherwise known as an arithmetic) r The value from which is subtracted. - The value which is subtracted from . + The value that is subtracted from . Subtracts two values to compute their difference. The difference of subtracted from . To be added. @@ -3518,7 +3518,7 @@ This operation is meant to perform n unsigned (otherwise known as a logical) rig - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -3552,7 +3552,7 @@ This operation is meant to perform n unsigned (otherwise known as a logical) rig - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/UInt16.xml b/xml/System/UInt16.xml index 21c81187551..53dba2a54ea 100644 --- a/xml/System/UInt16.xml +++ b/xml/System/UInt16.xml @@ -710,8 +710,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2203,7 +2203,7 @@ For this method matches the IEEE 754:2 - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2243,7 +2243,7 @@ For this method matches the IEEE 754:2 - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/UInt32.xml b/xml/System/UInt32.xml index 3d1041eb51b..be3dab730fc 100644 --- a/xml/System/UInt32.xml +++ b/xml/System/UInt32.xml @@ -744,8 +744,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2252,7 +2252,7 @@ For this method matches the IEEE 754:2 - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2292,7 +2292,7 @@ For this method matches the IEEE 754:2 - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/UInt64.xml b/xml/System/UInt64.xml index 68a8c74168d..f31dfe411f5 100644 --- a/xml/System/UInt64.xml +++ b/xml/System/UInt64.xml @@ -742,8 +742,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2231,7 +2231,7 @@ For this method matches the IEEE 754:2 - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2271,7 +2271,7 @@ For this method matches the IEEE 754:2 - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/System/UIntPtr.xml b/xml/System/UIntPtr.xml index 2acb196eb3c..ec9e455c8d6 100644 --- a/xml/System/UIntPtr.xml +++ b/xml/System/UIntPtr.xml @@ -774,7 +774,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, saturating any values that fall outside the representable range of the current type. An instance of created from , saturating if falls outside the representable range of . To be added. @@ -826,7 +826,7 @@ The type of . - The value which is used to create the instance of . + The value that is used to create the instance of . Creates an instance of the current type from a value, truncating any values that fall outside the representable range of the current type. An instance of created from , truncating if falls outside the representable range of . To be added. @@ -871,8 +871,8 @@ - The value which divides. - The value which divides . + The value that divides. + The value that divides . Computes the quotient and remainder of two values. The quotient and remainder of divided-by . To be added. @@ -2499,7 +2499,7 @@ For this method matches the IEEE 754:2 - The value which is rotated left by . + The value that is rotated left by . The amount by which is rotated left. Rotates a value left by a given amount. The result of rotating left by . @@ -2539,7 +2539,7 @@ For this method matches the IEEE 754:2 - The value which is rotated right by . + The value that is rotated right by . The amount by which is rotated right. Rotates a value right by a given amount. The result of rotating right by . diff --git a/xml/ns-System.ComponentModel.Design.xml b/xml/ns-System.ComponentModel.Design.xml index 6f7f7246c09..04a0f404dd7 100644 --- a/xml/ns-System.ComponentModel.Design.xml +++ b/xml/ns-System.ComponentModel.Design.xml @@ -1,59 +1,41 @@ - Contains classes that developers can use to build custom design-time behavior for components and user interfaces for configuring components at design time. The design time environment provides systems that enable developers to arrange components and configure their properties. Some components may require specific design-time only behavior to function properly in a design time environment. It may also be valuable to provide custom user interfaces which assist developers in configuring components or the values of complex data types. The classes and interfaces defined within this namespace can be used to build design-time behavior for components, access design-time services, and implement customized design-time configuration interfaces. + Contains classes that developers can use to build custom design-time behavior for components and user interfaces for configuring components at design time. The design-time environment provides systems that enable developers to arrange components and configure their properties. Some components might require specific design-time only behavior to function properly in a design-time environment. It might also be valuable to provide custom user interfaces that assist developers in configuring components or the values of complex data types. The classes and interfaces defined within this namespace can be used to build design-time behavior for components, access design-time services, and implement customized design-time configuration interfaces. interface that you can use to customize design-time behavior for specific types of components. - -- A class that provides a more sophisticated designer base class which implements the , , and interfaces. - -- Designer interfaces and services that enable a designer to support additional functionality, including: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- Classes that can be used to customize design-time license context management and serialization: and . - -- Simple collection editors that can be extended: and . +- A basic interface that you can use to customize design-time behavior for specific types of components. + +- A class that provides a more sophisticated designer base class that implements the , , and interfaces. + +- Designer interfaces and services that enable a designer to support additional functionality, including: + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + +- Classes that can be used to customize design-time license context management and serialization: and . + +- Simple collection editors that can be extended: and . ]]> diff --git a/xml/ns-System.Net.PeerToPeer.xml b/xml/ns-System.Net.PeerToPeer.xml index 0951db3c0d7..e48dba0c3b9 100644 --- a/xml/ns-System.Net.PeerToPeer.xml +++ b/xml/ns-System.Net.PeerToPeer.xml @@ -5,19 +5,15 @@ in a completely peer-to-peer manner. + Peer Name Resolution Protocol (PNRP) provides a name resolution mechanism for peer-to-peer networks. PNRP is designed to resolve a name to a network in a completely peer-to-peer manner. - Basic PNRP functionality is provided in the namespace classes. They provide the ability to create a peer and register it in a of peers. They also provide the ability to resolve a to its network endpoint, TCP port, cloud, or other address identifier(s). + Basic PNRP functionality is provided in the namespace classes. They provide the ability to create a peer and register it in a of peers. They also provide the ability to resolve a to its network endpoint, TCP port, cloud, or other address identifiers. Advanced functionality for peer-to-peer networking is provided in the namespace. - In Windows Vista, PNRP ships as a service that is started on demand by applications. In addition, there is a PNRP machine registration service that can be manually enabled by applications or users if they want to publish machine names for remote connections and communications. - - PNRP version 1 was included in Windows XP Service Pack 2 (SP2), Windows XP Professional x64 Edition, and Windows XP with Service Pack 1 (SP1) and the Advanced Networking Pack for Windows XP. - - In addition, there is a PNRP machine registration service which can be manually enabled by applications/users if there is interest in publishing machine names for remote connection and communication. + In Windows, PNRP ships as a service that's started on demand by applications. In addition, there is a PNRP machine registration service that can be manually enabled by applications or users if they want to publish machine names for remote connections and communications. ]]> diff --git a/xml/ns-System.Runtime.InteropServices.Expando.xml b/xml/ns-System.Runtime.InteropServices.Expando.xml index e0d7a838a64..6ba43e7bb58 100644 --- a/xml/ns-System.Runtime.InteropServices.Expando.xml +++ b/xml/ns-System.Runtime.InteropServices.Expando.xml @@ -1,6 +1,6 @@ - Contains the interface which allows modification of an object by adding or removing its members. + Contains the interface, which allows modification of an object by adding or removing its members. To be added. diff --git a/xml/ns-System.ServiceProcess.xml b/xml/ns-System.ServiceProcess.xml index 35df339c721..026b71f64c4 100644 --- a/xml/ns-System.ServiceProcess.xml +++ b/xml/ns-System.ServiceProcess.xml @@ -5,7 +5,7 @@ namespace provides installation classes that write service information to the registry. The class provides an encompassing class which installs components common to all the services in an installation. For each service, you create an instance of the class to install service-specific functionality. + Services are installed using an installation utility such as InstallUtil.exe. The namespace provides installation classes that write service information to the registry. The class provides an encompassing class that installs components common to all the services in an installation. For each service, you create an instance of the class to install service-specific functionality. The class enables you to connect to an existing service and manipulate it or get information about it. This class is typically used in an administrative capacity, and enables you to start, stop, pause, continue, or perform custom commands on a service. Where the class defines the processing a service performs when a command occurs, the is the agent that enables you to call those commands on the service. diff --git a/xml/ns-System.Speech.Recognition.xml b/xml/ns-System.Speech.Recognition.xml index fd3039b223f..3f03e6d7127 100644 --- a/xml/ns-System.Speech.Recognition.xml +++ b/xml/ns-System.Speech.Recognition.xml @@ -5,9 +5,9 @@ namespace to access and extend this basic speech recognition technology by defining algorithms for identifying and acting on specific phrases or word patterns, and by managing the runtime behavior of this speech infrastructure. + Applications use the namespace to access and extend this basic speech recognition technology by defining algorithms for identifying and acting on specific phrases or word patterns, and by managing the run-time behavior of this speech infrastructure. **Create Grammars** @@ -17,8 +17,6 @@ In addition, the class provides a special-case grammar to support a conventional dictation model. - See [Create Grammars](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361675(v=office.14)) in the [System Speech Programming Guide for .NET Framework](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361625(v%3doffice.14)) for more information and examples. - **Manage Speech Recognition Engines** Instances of and supplied with objects provide the primary access to the speech recognition engines of the Windows Desktop Speech Technology. @@ -27,27 +25,19 @@ For more control over the configuration and type of recognition engine, build an application using , which runs in-process. Using the class, you can also dynamically select audio input from devices, files, or streams. - See [Initialize and Manage a Speech Recognition Engine](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361636(v=office.14)) in the [System Speech Programming Guide for .NET Framework](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361625(v%3doffice.14)) for more information. - **Respond to Events** - and objects generate events in response to audio input to the speech recognition engine. The `AudioLevelUpdated`, `AudioSignalProblemOccurred`, `AudioStateChanged` events are raised in response to changes in the incoming signal. The `SpeechDetected` event is raised when the speech recognition engine identifies incoming audio as speech. The speech recognition engine raises the `SpeechRecognized` event when it matches speech input to one of its loaded grammars, and raises the `SpeechRecognitionRejected` when speech input does not match any of its loaded grammars. + and objects generate events in response to audio input to the speech recognition engine. The `AudioLevelUpdated`, `AudioSignalProblemOccurred`, and `AudioStateChanged` events are raised in response to changes in the incoming signal. The `SpeechDetected` event is raised when the speech recognition engine identifies incoming audio as speech. The speech recognition engine raises the `SpeechRecognized` event when it matches speech input to one of its loaded grammars, and raises the `SpeechRecognitionRejected` when speech input does not match any of its loaded grammars. - Other types of events include the `LoadGrammarCompleted` event which a speech recognition engine raises when it has loaded a grammar. The is exclusive to the class, which raises the event when the state of Windows Speech Recognition changes. + Other types of events include the `LoadGrammarCompleted` event, which a speech recognition engine raises when it has loaded a grammar. The is exclusive to the class, which raises the event when the state of Windows Speech Recognition changes. You can register to be notified for events that the speech recognition engine raises and create handlers using the `EventsArgs` classes associated with each of these events to program your application's behavior when an event is raised. - See [Using Speech Recognition Events](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361573(v=office.14)) in the [System Speech Programming Guide for .NET Framework](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361625(v%3doffice.14)) for more information. - ]]> - Speech Recognition - Create Grammars - Initialize and Manage a Speech Recognition Engine - Using Speech Recognition Events diff --git a/xml/ns-System.Threading.Tasks.xml b/xml/ns-System.Threading.Tasks.xml index d7a9aab72cc..514f64b276e 100644 --- a/xml/ns-System.Threading.Tasks.xml +++ b/xml/ns-System.Threading.Tasks.xml @@ -1,7 +1,7 @@ - Provides types that simplify the work of writing concurrent and asynchronous code. The main types are which represents an asynchronous operation that can be waited on and cancelled, and , which is a task that can return a value. The class provides static methods for creating and starting tasks, and the class provides the default thread scheduling infrastructure. + Provides types that simplify the work of writing concurrent and asynchronous code. The main types are , which represents an asynchronous operation that can be waited on and cancelled, and , which is a task that can return a value. The class provides static methods for creating and starting tasks, and the class provides the default thread scheduling infrastructure. To be added. - Parallel Programming in the .NET Framework + Parallel programming in .NET diff --git a/xml/ns-System.Xml.Resolvers.xml b/xml/ns-System.Xml.Resolvers.xml index 8c7bae9dd75..965cd1c2f6d 100644 --- a/xml/ns-System.Xml.Resolvers.xml +++ b/xml/ns-System.Xml.Resolvers.xml @@ -11,7 +11,7 @@ The enumeration defines which well-known DTDs the recognizes. The enumeration contains the `Xhtml10`, `Rss091`, `All`, and `None` values. - `XmlKnownDtd.Xhtml10` specifies that the `T:System.Xml.Resolvers.XmlPreloadedResolver` will recognize DTDs and entities that are defined in XHTML 1.0. For more information about XHTML, see the [XHTML 1.0 specification](https://go.microsoft.com/fwlink/?LinkID=109812). + `XmlKnownDtd.Xhtml10` specifies that the `T:System.Xml.Resolvers.XmlPreloadedResolver` will recognize DTDs and entities that are defined in XHTML 1.0. For more information about XHTML, see the [XHTML 1.0 specification](https://www.w3.org/TR/xhtml1/). `XmlKnownDtd.Rss091` specifies that the `T:System.Xml.Resolvers.XmlPreloadedResolver` will recognize DTDs and entities that are defined in RSS 0.91. @@ -20,7 +20,7 @@ `XmlKnownDtd.None` specifies that the will not recognize any of the predefined DTDs. > [!NOTE] -> When the preloads a well-known DTD, it does not invoke network connections because the DTDs are already embedded in the System.Xml.Utils assembly. +> When the preloads a well-known DTD, it does not invoke network connections because the DTDs are already embedded in the System.Xml.Utils assembly. ]]> diff --git a/xml/ns-System.Xml.xml b/xml/ns-System.Xml.xml index 931a2037868..dc8d2c2ccfe 100644 --- a/xml/ns-System.Xml.xml +++ b/xml/ns-System.Xml.xml @@ -11,41 +11,30 @@ The namespace supports these standards: - [XML 1.0, including DTD support](https://www.w3.org/TR/2006/REC-xml-20060816/) - - [XML namespaces](https://www.w3.org/TR/REC-xml-names/), both stream-level and DOM - - [XML schemas](https://www.w3.org/2001/XMLSchema) - - [XPath expressions](https://www.w3.org/TR/xpath) - - [XSLT transformations](https://www.w3.org/TR/xslt) - - [DOM Level 1 Core](https://www.w3.org/TR/REC-DOM-Level-1/) - - [DOM Level 2 Core](https://www.w3.org/TR/DOM-Level-2/) See the section [Differences from the W3C specs](#diff) for two cases in which the XML classes differ from the W3C recommendations. - -## Related namespaces - -.NET also provides other namespaces for XML-related operations. For a list, descriptions, and links, see [System.Xml Namespaces](/previous-versions/gg145036(v=vs.110)). - ## Processing XML asynchronously The and classes include a number of asynchronous methods that are based on the asynchronous programming model. These methods can be identified by the string "Async" at the end of their names. With these methods, you can write asynchronous code that's similar to your synchronous code, and you can migrate your existing synchronous code to asynchronous code easily. -- Use the asynchronous methods in apps where there is significant network stream latency. Avoid using the asynchronous APIs for memory stream or local file stream read/write operations. The input stream, , and should support asynchronous operations as well. Otherwise, threads will still be blocked by I/O operations. +- Use the asynchronous methods in apps where there is significant network stream latency. Avoid using the asynchronous APIs for memory stream or local file stream read/write operations. The input stream, , and should support asynchronous operations as well. Otherwise, threads will still be blocked by I/O operations. -- We don't recommend mixing synchronous and asynchronous function calls, because you might forget to use the `await` keyword or use a synchronous API where an asynchronous one is necessary. +- We don't recommend mixing synchronous and asynchronous function calls, because you might forget to use the `await` keyword or use a synchronous API where an asynchronous one is necessary. -- Do not set the or flag to `true` if you don't intend to use an asynchronous method. +- Do not set the or flag to `true` if you don't intend to use an asynchronous method. -- If you forget to specify the `await` keyword when you call an asynchronous method, the results are non-deterministic: You might receive the result you expected or an exception. +- If you forget to specify the `await` keyword when you call an asynchronous method, the results are non-deterministic: You might receive the result you expected or an exception. -- When an object is reading a large text node, it might cache only a partial text value and return the text node, so retrieving the property might be blocked by an I/O operation. Use the method to get the text value in asynchronous mode, or use the method to read a large text block in chunks. +- When an object is reading a large text node, it might cache only a partial text value and return the text node, so retrieving the property might be blocked by an I/O operation. Use the method to get the text value in asynchronous mode, or use the method to read a large text block in chunks. -- When you use an object, call the method before calling to avoid blocking an I/O operation. +- When you use an object, call the method before calling to avoid blocking an I/O operation. ## Differences from the W3C specs @@ -87,15 +76,11 @@ Under the following conditions, the implementation does not satisfy the "Schema Component Constraint: Unique Particle Attribution," which is described in the [Constraints on Model Group Schema Components](https://go.microsoft.com/fwlink/?LinkId=137029) section of the W3C spec. -- One of the elements in the group references another element. - -- The referenced element is a head element of a substitution group. - -- The substitution group contains an element that has the same name as one of the elements in the group. - -- The cardinality of the element that references the substitution group head element and the element with the same name as a substitution group element is not fixed (minOccurs < maxOccurs). - -- The definition of the element that references the substitution group precedes the definition of the element with the same name as a substitution group element. +- One of the elements in the group references another element. +- The referenced element is a head element of a substitution group. +- The substitution group contains an element that has the same name as one of the elements in the group. +- The cardinality of the element that references the substitution group head element and the element with the same name as a substitution group element is not fixed (minOccurs < maxOccurs). +- The definition of the element that references the substitution group precedes the definition of the element with the same name as a substitution group element. For example, in the schema below the content model is ambiguous and should cause a compilation error, but compiles the schema without errors. @@ -184,27 +169,27 @@ The following scenarios are considered to be less vulnerable to denial of service attacks because the classes provide a means of protection from such attacks. -- Parsing text XML data. +- Parsing text XML data. -- Parsing binary XML data if the binary XML data was generated by Microsoft SQL Server. +- Parsing binary XML data if the binary XML data was generated by Microsoft SQL Server. -- Writing XML documents and fragments from data sources to the file system, streams, a , or a . +- Writing XML documents and fragments from data sources to the file system, streams, a , or a . -- Loading documents into the Document Object Model (DOM) object if you are using an object and set to . +- Loading documents into the Document Object Model (DOM) object if you are using an object and set to . -- Navigating the DOM object. +- Navigating the DOM object. The following scenarios are not recommended if you are concerned about denial of service attacks, or if you are working in an untrusted environment. -- DTD processing. +- DTD processing. -- Schema processing. This includes adding an untrusted schema to the schema collection, compiling an untrusted schema, and validating by using an untrusted schema. +- Schema processing. This includes adding an untrusted schema to the schema collection, compiling an untrusted schema, and validating by using an untrusted schema. -- XSLT processing. +- XSLT processing. -- Parsing any arbitrary stream of user supplied binary XML data. +- Parsing any arbitrary stream of user supplied binary XML data. -- DOM operations such as querying, editing, moving sub-trees between documents, and saving DOM objects. +- DOM operations such as querying, editing, moving sub-trees between documents, and saving DOM objects. If you are concerned about denial of service issues or if you are dealing with untrusted sources, do not enable DTD processing. This is disabled by default on objects that the method creates. @@ -223,15 +208,15 @@ When creating an app that uses the class, you should be aware of the following items and their implications: -- XSLT scripting is disabled by default. XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. +- XSLT scripting is disabled by default. XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. -- The XSLT `document()` function is disabled by default. If you enable the `document()` function, restrict the resources that can be accessed by passing an object to the method. +- The XSLT `document()` function is disabled by default. If you enable the `document()` function, restrict the resources that can be accessed by passing an object to the method. -- Extension objects are enabled by default. If an object that contains extension objects is passed to the method, the extension objects are used. +- Extension objects are enabled by default. If an object that contains extension objects is passed to the method, the extension objects are used. -- XSLT style sheets can include references to other files and embedded script blocks. A malicious user can exploit this by supplying you with data or style sheets that, when executed, can cause your system to process until the computer runs low on resources. +- XSLT style sheets can include references to other files and embedded script blocks. A malicious user can exploit this by supplying you with data or style sheets that, when executed, can cause your system to process until the computer runs low on resources. -- XSLT apps that run in a mixed trust environment can result in style sheet spoofing. For example, a malicious user can load an object with a harmful style sheet and hand it off to another user who subsequently calls the method and executes the transformation. +- XSLT apps that run in a mixed trust environment can result in style sheet spoofing. For example, a malicious user can load an object with a harmful style sheet and hand it off to another user who subsequently calls the method and executes the transformation. These security issues can be mitigated by not enabling scripting or the `document()` function unless the style sheet comes from a trusted source, and by not accepting objects, XSLT style sheets, or XML source data from an untrusted source.