diff --git a/includes/context.md b/includes/context.md deleted file mode 100644 index 48e7573b5ca..00000000000 --- a/includes/context.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> This article provides supplementary remarks to the reference documentation for this API. diff --git a/includes/dependencypropertyremark-md.md b/includes/dependencypropertyremark-md.md deleted file mode 100644 index fab6dc31270..00000000000 --- a/includes/dependencypropertyremark-md.md +++ /dev/null @@ -1 +0,0 @@ -You indirectly access each public property and event of this type by the resolution of a corresponding dependency property. This dependency property is the public static field named **XProperty** or **XEvent**, where X is the corresponding property. \ No newline at end of file diff --git a/includes/deprecatedcontent-md.md b/includes/deprecatedcontent-md.md deleted file mode 100644 index 0907e3b584c..00000000000 --- a/includes/deprecatedcontent-md.md +++ /dev/null @@ -1 +0,0 @@ -This material discusses types and namespaces that are obsolete. For more information, see [Deprecated Types in Windows Workflow Foundation 4.5](https://aka.ms/wfdeprecatedtypes). \ No newline at end of file diff --git a/includes/forms-auth-warning.md b/includes/forms-auth-warning.md deleted file mode 100644 index e364edc46cb..00000000000 --- a/includes/forms-auth-warning.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!WARNING] -> Storing user credentials in the `credentials` section is **insecure**. Instead, use [Azure Key Vault](/azure/key-vault/general/overview). diff --git a/includes/note-compatibility-md.md b/includes/note-compatibility-md.md deleted file mode 100644 index 1d43adaf52d..00000000000 --- a/includes/note-compatibility-md.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> Functions and objects in the namespace are provided for use by the tools for upgrading from Visual Basic 6.0 to Visual Basic 2008. In most cases, these functions and objects duplicate functionality that you can find in other namespaces in the .NET Framework. They are necessary only when the Visual Basic 6.0 code model differs significantly from the .NET Framework implementation. \ No newline at end of file diff --git a/includes/System.Windows.Forms.PictureBox/load-behavior-changes.md b/includes/picturebox-load-behavior-changes.md similarity index 100% rename from includes/System.Windows.Forms.PictureBox/load-behavior-changes.md rename to includes/picturebox-load-behavior-changes.md diff --git a/includes/remarks/System/String/provider-string-format.md b/includes/provider-string-format.md similarity index 100% rename from includes/remarks/System/String/provider-string-format.md rename to includes/provider-string-format.md diff --git a/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md b/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md deleted file mode 100644 index c9318b19777..00000000000 --- a/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md +++ /dev/null @@ -1,18 +0,0 @@ -Compression operations usually involve a tradeoff between the speed and the effectiveness of compression. You use the enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. - -The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: - -- -- -- -- -- -- -- - -## Examples - -The following example shows how to set the compression level when creating a zip archive by using the class. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipFile/CreateFromDirectory/program3.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipFile/CreateFromDirectory/program3.vb" id="Snippet3"::: diff --git a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md deleted file mode 100644 index 4ce0d1df2a4..00000000000 --- a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md +++ /dev/null @@ -1,8 +0,0 @@ -This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - -## Examples - -The following example shows how to set the compression level when creating a object and how to leave the stream open. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionLevelExample.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionLevelExample.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md deleted file mode 100644 index 766ba4c57e1..00000000000 --- a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md +++ /dev/null @@ -1,12 +0,0 @@ -By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. - -If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. - -By default, the compression level is set to when the compression mode is . - -## Examples - -The following example shows how to use the class to compress and decompress a file. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionModeExample.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionModeExample.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md b/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md deleted file mode 100644 index 8be8dea016d..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md +++ /dev/null @@ -1,18 +0,0 @@ -If the `mode` parameter is set to , the stream must support reading. If the `mode` parameter is set to , the stream must support writing. If the `mode` parameter is set to , the stream must support reading, writing, and seeking. - -When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names and comments are decoded according to the following rules: - -- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name and comment. -- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. - -When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules: - -- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name and comment. -- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. - -When you write to archive files and `entryNameEncoding` is set to `null`, entry names and comments are encoded according to the following rules: - -- For entry names and comments that contain characters outside the ASCII range, the language encoding flag is set, and entry names and comments are encoded by using UTF-8. -- For entry names and comments that contain only ASCII characters, the language encoding flag is not set, and entry names and comments are encoded by using the current system default code page. - -When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names and comments into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. diff --git a/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md b/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md deleted file mode 100644 index 4361957ded0..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md +++ /dev/null @@ -1,32 +0,0 @@ -The methods for manipulating zip archives and their file entries are spread across three classes: , , and . - -|To|Use| -|--------|---------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve a file from a zip archive|| -|Retrieve all the files from a zip archive|| -|Open a stream to a single file contained in a zip archive|| -|Delete a file from a zip archive|| - -When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. - -If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types and . - -## Examples - -The first example shows how to create a new entry and write to it by using a stream. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: - -The following example shows how to open a zip archive and iterate through the collection of entries. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: - -The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program3.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program3.vb" id="Snippet3"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md deleted file mode 100644 index c669c3c31d9..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md +++ /dev/null @@ -1,10 +0,0 @@ -The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. - -You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. - -## Examples - -The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md deleted file mode 100644 index e78d01eb5e3..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md +++ /dev/null @@ -1,10 +0,0 @@ -When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. - -When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). - -## Examples - -The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program2.cs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program2.vb" id="Snippet2"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md deleted file mode 100644 index 369b7e1e413..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md +++ /dev/null @@ -1,9 +0,0 @@ -The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. -On Windows, colons (`:`) are also treated as separators due to NTFS rules, which can cause to differ across platforms. For platform-independent behavior, you can use , which always reflects the complete entry name as stored in the archive. - -## Examples - -The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md deleted file mode 100644 index 2d2ee597580..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md +++ /dev/null @@ -1,27 +0,0 @@ -A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - -The methods for manipulating zip archives and their file entries are spread across three classes: , and . - -|To...|Use...| -|---------|----------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve a file in a zip archive|| -|Retrieve all of the files in a zip archive|| -|To open a stream to an individual file contained in a zip archive|| -|Delete a file from a zip archive|| - -If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types and to compress and decompress files. - -## Examples - -The first example shows how to create a new entry in a zip archive and write to it. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: - -The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md b/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md deleted file mode 100644 index 82e41ac61ee..00000000000 --- a/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md +++ /dev/null @@ -1,20 +0,0 @@ -When you set the mode to Read, the underlying file or stream must support reading, but does not have to support seeking. If the underlying file or stream supports seeking, the files are read from the archive as they are requested. If the underlying file or stream does not support seeking, the entire archive is held in memory. - -When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. - -When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. - -The following methods include a parameter named `mode` that lets you specify the archive mode: - -- - -- - -- - -## Examples - -The following example shows how to specify a `ZipArchiveMode` value when creating a object. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipFile/Open.md b/includes/remarks/System.IO.Compression/ZipFile/Open.md deleted file mode 100644 index 572d81b4c1b..00000000000 --- a/includes/remarks/System.IO.Compression/ZipFile/Open.md +++ /dev/null @@ -1,22 +0,0 @@ -When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. - -When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - -When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. - -When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names and comments are decoded according to the following rules: - -- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name and comment. -- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. - -When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules: - -- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name and comment. -- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. - -When you write to archive files and `entryNameEncoding` is set to `null`, entry names and comments are encoded according to the following rules: - -- For entry names or comments that contain characters outside the ASCII range, the language encoding flag is set, and entry names and comments are encoded by using UTF-8. -- For entry names or comments that contain only ASCII characters, the language encoding flag is not set, and entry names and comments are encoded by using the current system default code page. - -When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names and comments into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. diff --git a/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md b/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md deleted file mode 100644 index 489afac7817..00000000000 --- a/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md +++ /dev/null @@ -1,21 +0,0 @@ -> [!NOTE] -> To use the class in a .NET Framework app, you must add a reference to the `System.IO.Compression.FileSystem` assembly in your project. For information on how to add a reference to your project in Visual Studio, see [How to: Add or Remove References](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager). - -The methods for manipulating zip archives and their files are spread across three classes: , , and . - -| To... | Use... | -|---------------------------------------|--------| -| Create a zip archive from a directory | | -| Extract the contents of a zip archive to a directory | | -| Add new files to an existing zip archive | | -| Retrieve a file in a zip archive | | -| Retrieve all of the files in a zip archive | | -| Open a stream to an individual file contained in a zip archive| | -| Delete a file from a zip archive | | - -## Examples - -This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipFile/CreateFromDirectory/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipFile/CreateFromDirectory/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md b/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md deleted file mode 100644 index eea3bc321eb..00000000000 --- a/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md +++ /dev/null @@ -1,31 +0,0 @@ -The class contains only static methods that extend the and classes. You do not create an instance of the class; instead, you use these methods from instances of or . - -To use the extension methods, you must reference the `System.IO.Compression.FileSystem` assembly in your project. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8.x Store apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in Windows 8.x Store apps. In Windows 8.x Store apps, you work with compressed files by using the methods in , , , and . - -The class contains four methods that extend : - -- - -- - -- - -- - -The class contains two methods that extend : - -- - -- - -## Examples - -The following example shows how to create a new entry in a zip archive from an existing file, and extract the contents of the archive to a directory. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program3.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program3.vb" id="Snippet3"::: - -The following example shows how to iterate through the contents of a zip archive and extract files that have a .txt extension. - -:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: diff --git a/includes/remarks/System/String/simple-string-format.md b/includes/simple-string-format.md similarity index 100% rename from includes/remarks/System/String/simple-string-format.md rename to includes/simple-string-format.md diff --git a/includes/system-json.md b/includes/system-json.md deleted file mode 100644 index 5286deaf0ba..00000000000 --- a/includes/system-json.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> The namespace was designed for Silverlight, which is no longer supported. For processing JSON, we recommend using APIs in the namespace instead. diff --git a/includes/unnamed-parm-md.md b/includes/unnamed-parm-md.md deleted file mode 100644 index 0562e2499e3..00000000000 --- a/includes/unnamed-parm-md.md +++ /dev/null @@ -1 +0,0 @@ -Some methods, especially operators, declare a type for a parameter but do not specify a parameter name. Such a parameter is known as an *unnamed parameter*. In the documentation for these methods, the *A_0* placeholder represents the unnamed parameter. diff --git a/includes/remarks/System.Threading/WaitHandle/exit-context.md b/includes/waithandle-exit-context.md similarity index 100% rename from includes/remarks/System.Threading/WaitHandle/exit-context.md rename to includes/waithandle-exit-context.md diff --git a/includes/wif-saml2-ref-md.md b/includes/wif-saml2-ref-md.md deleted file mode 100644 index 1e7ffa5ad63..00000000000 --- a/includes/wif-saml2-ref-md.md +++ /dev/null @@ -1 +0,0 @@ -For more information about the element that this class represents, see the following specification: [Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf). diff --git a/includes/wif-wsfed-ref-md.md b/includes/wif-wsfed-ref-md.md deleted file mode 100644 index 255ed0b5e1e..00000000000 --- a/includes/wif-wsfed-ref-md.md +++ /dev/null @@ -1 +0,0 @@ -For more information about the message that this class represents, see section 13 of the following specification: [Web Services Federation Language (WS-Federation) Version 1.2](https://docs.oasis-open.org/wsfed/federation/v1.2/os/ws-federation-1.2-spec-os.html). diff --git a/includes/wif-wstrust-ref-md.md b/includes/wif-wstrust-ref-md.md deleted file mode 100644 index b989044a7f1..00000000000 --- a/includes/wif-wstrust-ref-md.md +++ /dev/null @@ -1 +0,0 @@ -For more information about the element that this class represents, see the WS-Trust specification that applies to your scenario: [WS-Trust February 2005](https://schemas.xmlsoap.org/ws/2005/02/trust/), [WS-Trust 1.3](https://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust-1.3-os.html), or [WS-Trust 1.4](https://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.html). diff --git a/includes/xmlreader-read-sample-output.md b/includes/xmlreader-read-output.md similarity index 98% rename from includes/xmlreader-read-sample-output.md rename to includes/xmlreader-read-output.md index 836c6a82e74..21800f93a41 100644 --- a/includes/xmlreader-read-sample-output.md +++ b/includes/xmlreader-read-output.md @@ -1,3 +1,3 @@ ```xml Test with an entity: 123Test with a child element stuffTest with a CDATA section ]]> defTest with a char entity: A1234567890ABCD -``` +``` \ No newline at end of file diff --git a/includes/xsltransform-script.md b/includes/xsltransform-script.md deleted file mode 100644 index 44d6b32f455..00000000000 --- a/includes/xsltransform-script.md +++ /dev/null @@ -1,7 +0,0 @@ - ```xml - - - -``` \ No newline at end of file diff --git a/xml/System.IO.Compression/CompressionLevel.xml b/xml/System.IO.Compression/CompressionLevel.xml index 0f7aeaa478a..fa1349287a8 100644 --- a/xml/System.IO.Compression/CompressionLevel.xml +++ b/xml/System.IO.Compression/CompressionLevel.xml @@ -47,7 +47,24 @@ enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. + +The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: + +- +- +- +- +- +- +- + +## Examples + +The following example shows how to set the compression level when creating a zip archive by using the class. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipFile/CreateFromDirectory/program3.cs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipFile/CreateFromDirectory/program3.vb" id="Snippet3"::: ]]> diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index ed1fc0d3daa..2a760da5038 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -134,7 +134,14 @@ The following example shows how to use the class. -[!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md)] +This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + +## Examples + +The following example shows how to set the compression level when creating a object and how to leave the stream open. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionLevelExample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionLevelExample.vb" id="Snippet1"::: ]]> @@ -187,7 +194,18 @@ You use this constructor when you want to specify whether compression efficiency owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + +If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + +By default, the compression level is set to when the compression mode is . + +## Examples + +The following example shows how to use the class to compress and decompress a file. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionModeExample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionModeExample.vb" id="Snippet1"::: ]]> @@ -255,7 +273,14 @@ You use this constructor when you want to specify whether compression efficiency You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. -[!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md)] +This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + +## Examples + +The following example shows how to set the compression level when creating a object and how to leave the stream open. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionLevelExample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionLevelExample.vb" id="Snippet1"::: ]]> @@ -311,7 +336,18 @@ You use this constructor when you want to specify whether compression efficiency owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + +If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + +By default, the compression level is set to when the compression mode is . + +## Examples + +The following example shows how to use the class to compress and decompress a file. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/FileCompressionModeExample.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/Deflate/FileCompressionModeExample.vb" id="Snippet1"::: ]]> diff --git a/xml/System.IO.Compression/ZipArchive.xml b/xml/System.IO.Compression/ZipArchive.xml index f194e69f2bc..a1ffa5776c7 100644 --- a/xml/System.IO.Compression/ZipArchive.xml +++ b/xml/System.IO.Compression/ZipArchive.xml @@ -62,7 +62,38 @@ , , and . + +|To|Use| +|--------|--------| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve a file from a zip archive|| +|Retrieve all the files from a zip archive|| +|Open a stream to a single file contained in a zip archive|| +|Delete a file from a zip archive|| + +When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. + +The class provides four extension methods for the type: , , , and . These extension methods enable you to compress and decompress the contents of the entry to a file. + +## Examples + +The first example shows how to create a new entry and write to it by using a stream. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: + +The following example shows how to open a zip archive and iterate through the collection of entries. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: + +The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program3.cs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program3.vb" id="Snippet3"::: ]]> @@ -293,7 +324,24 @@ , the stream must support reading. If the `mode` parameter is set to , the stream must support writing. If the `mode` parameter is set to , the stream must support reading, writing, and seeking. + +When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names and comments are decoded according to the following rules: + +- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name and comment. +- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. + +When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules: + +- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name and comment. +- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. + +When you write to archive files and `entryNameEncoding` is set to `null`, entry names and comments are encoded according to the following rules: + +- For entry names and comments that contain characters outside the ASCII range, the language encoding flag is set, and entry names and comments are encoded by using UTF-8. +- For entry names and comments that contain only ASCII characters, the language encoding flag is not set, and entry names and comments are encoded by using the current system default code page. + +When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names and comments into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. ]]> diff --git a/xml/System.IO.Compression/ZipArchiveEntry.xml b/xml/System.IO.Compression/ZipArchiveEntry.xml index 26f90366650..b67fdaef3b1 100644 --- a/xml/System.IO.Compression/ZipArchiveEntry.xml +++ b/xml/System.IO.Compression/ZipArchiveEntry.xml @@ -50,7 +50,33 @@ class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. + +The methods for manipulating zip archives and their file entries are spread across three classes: , , and . + +| To... | Use... | +|---------------------------------------|--------| +| Create a zip archive from a directory | | +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve a file in a zip archive|| +|Retrieve all of the files in a zip archive|| +|To open a stream to an individual file contained in a zip archive|| +|Delete a file from a zip archive|| + +The class provides extension methods for , such as and , which enable you to decompress the contents of the entry to a file. + +## Examples + +The first example shows how to create a new entry in a zip archive and write to it. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: + +The second example shows how to use the extension method. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: ]]> @@ -359,7 +385,16 @@ If the comment byte length is larger than , it will property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\NewEntry.txt` in the property. + +You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. + +## Examples + +The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: ]]> @@ -429,7 +464,16 @@ If the comment byte length is larger than , it will method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. + +When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). + +## Examples + +The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program2.cs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program2.vb" id="Snippet2"::: ]]> @@ -528,7 +572,16 @@ If the comment byte length is larger than , it will property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\NewEntry.txt` in the property. + +On Windows, colons (`:`) are also treated as separators due to NTFS rules, which can cause to differ across platforms. For platform-independent behavior, you can use , which always reflects the complete entry name as stored in the archive. + +## Examples + +The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: ]]> diff --git a/xml/System.IO.Compression/ZipArchiveMode.xml b/xml/System.IO.Compression/ZipArchiveMode.xml index dedec63791a..d5a03a8f8fe 100644 --- a/xml/System.IO.Compression/ZipArchiveMode.xml +++ b/xml/System.IO.Compression/ZipArchiveMode.xml @@ -43,7 +43,26 @@ method, the data is written to the underlying stream or file after all the entries are created. + +When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. + +The following methods include a parameter named `mode` that lets you specify the archive mode: + +- + +- + +- + +## Examples + +The following example shows how to specify a `ZipArchiveMode` value when creating a object. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: ]]> diff --git a/xml/System.IO.Compression/ZipFile.xml b/xml/System.IO.Compression/ZipFile.xml index 52a22ba6129..8f80b442297 100644 --- a/xml/System.IO.Compression/ZipFile.xml +++ b/xml/System.IO.Compression/ZipFile.xml @@ -54,7 +54,24 @@ , , and . + +| To... | Use... | +|---------------------------------------|--------| +| Create a zip archive from a directory | | +| Extract the contents of a zip archive to a directory | | +| Add new files to an existing zip archive | | +| Retrieve a file in a zip archive | | +| Retrieve all of the files in a zip archive | | +| Open a stream to an individual file contained in a zip archive| | +| Delete a file from a zip archive | | + +## Examples + +This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipFile/CreateFromDirectory/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipFile/CreateFromDirectory/program1.vb" id="Snippet1"::: ]]> @@ -2501,7 +2518,7 @@ An archive entry has been compressed using a compression method that isn't suppo When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. ## Examples The following example shows how to open a zip archive in the update mode and add an entry to the archive. @@ -2610,7 +2627,28 @@ An unspecified I/O error occurred while opening the file. , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. + +When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + +When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. + +When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names and comments are decoded according to the following rules: + +- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name and comment. +- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. + +When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names and comments are decoded according to the following rules: + +- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name and comment. +- When the language encoding flag is set, UTF-8 is used to decode the entry name and comment. + +When you write to archive files and `entryNameEncoding` is set to `null`, entry names and comments are encoded according to the following rules: + +- For entry names or comments that contain characters outside the ASCII range, the language encoding flag is set, and entry names and comments are encoded by using UTF-8. +- For entry names or comments that contain only ASCII characters, the language encoding flag is not set, and entry names and comments are encoded by using the current system default code page. + +When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names and comments into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. ]]> diff --git a/xml/System.IO.Compression/ZipFileExtensions.xml b/xml/System.IO.Compression/ZipFileExtensions.xml index db8d0a85e76..db1875a39d0 100644 --- a/xml/System.IO.Compression/ZipFileExtensions.xml +++ b/xml/System.IO.Compression/ZipFileExtensions.xml @@ -58,7 +58,29 @@ class contains four methods that extend : + +- +- +- +- + +The class contains two methods that extend : + +- +- + +## Examples + +The following example shows how to create a new entry in a zip archive from an existing file, and extract the contents of the archive to a directory. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program3.cs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program3.vb" id="Snippet3"::: + +The following example shows how to iterate through the contents of a zip archive and extract files that have a .txt extension. + +:::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index 593672fe2e9..3bc29c91c38 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -68,8 +68,6 @@ > [!IMPORTANT] > We recommend that you don't use the `SecureString` class for new development on .NET (Core) or when you migrate from .NET Framework. For more information, see [SecureString shouldn't be used](https://github.com/dotnet/platform-compat/blob/master/docs/DE0001.md). -[!INCLUDE [context](~/includes/context.md)] - is a string type that provides a measure of security. It tries to avoid storing potentially sensitive strings in process memory as plain text. (For limitations, however, see the [How secure is SecureString?](#how-secure-is-securestring) section.) The value of an instance of is automatically protected using a mechanism supported by the underlying platform when the instance is initialized or when the value is modified. Your application can render the instance immutable and prevent further modification by invoking the method. The maximum length of a instance is 65,536 characters. diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index b0ac5db5583..7a0589e7671 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -658,7 +658,7 @@ This operation is not guaranteed to be atomic. After the current thread signals If `millisecondsTimeout` is zero, the method does not block. It tests the state of the `toWaitOn` and returns immediately. -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ]]> @@ -735,7 +735,7 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state If `timeout` is zero, the method does not block. It tests the state of the `toWaitOn` and returns immediately. -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ]]> @@ -1088,7 +1088,7 @@ The method returns when the wait ter > [!NOTE] > The method is not supported on threads in state. -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. @@ -1184,7 +1184,7 @@ The method returns when the wait ter The maximum value for `timeout` is . -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. @@ -1527,7 +1527,7 @@ This method returns when the wait terminates, either when any of the handles are The maximum number of the wait handles is 64, and 63 if the current thread is in state. -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. @@ -1614,7 +1614,7 @@ The maximum number of the wait handles is 64, and 63 if the current thread is in The maximum value for `timeout` is . -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following code example demonstrates how to use the thread pool to simultaneously search for a file on multiple disks. For space considerations, only the root directory of each disk is searched. @@ -1926,7 +1926,7 @@ The caller of this method blocks until the current instance receives a signal or Override this method to customize the behavior of derived classes. -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following example shows how the method overload behaves when it is called within a synchronization domain. First, a thread waits with `exitContext` set to `false` and blocks until the wait timeout expires. A second thread executes after the first thread terminates and waits with `exitContext` set to `true`. The call to signal the wait handle for this second thread is not blocked, and the thread completes before the wait timeout. @@ -2005,7 +2005,7 @@ Override this method to customize the behavior of derived classes. The maximum value for `timeout` is . -[!INCLUDE [Exit the context](~/includes/remarks/System.Threading/WaitHandle/exit-context.md)] +[!INCLUDE [Exit the context](~/includes/waithandle-exit-context.md)] ## Examples The following code example shows how to use a wait handle to keep a process from terminating while it waits for a background thread to finish executing. diff --git a/xml/System.Windows.Forms/PictureBox.xml b/xml/System.Windows.Forms/PictureBox.xml index c3309f8861b..5a2d0ed3794 100644 --- a/xml/System.Windows.Forms/PictureBox.xml +++ b/xml/System.Windows.Forms/PictureBox.xml @@ -1226,7 +1226,7 @@ @@ -1272,7 +1272,7 @@ If the `url` parameter indicates a local file, the recommended format is a local ### Load behavior changes -[!INCLUDE[drawing](~/includes/System.Windows.Forms.PictureBox/load-behavior-changes.md)] +[!INCLUDE[drawing](~/includes/picturebox-load-behavior-changes.md)] ]]> @@ -1332,7 +1332,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ### Load behavior changes -[!INCLUDE[drawing](~/includes/System.Windows.Forms.PictureBox/load-behavior-changes.md)] +[!INCLUDE[drawing](~/includes/picturebox-load-behavior-changes.md)] ]]> @@ -1379,7 +1379,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ### Load behavior changes -[!INCLUDE[drawing](~/includes/System.Windows.Forms.PictureBox/load-behavior-changes.md)] +[!INCLUDE[drawing](~/includes/picturebox-load-behavior-changes.md)] ## Examples diff --git a/xml/System.Xml/XmlReader.xml b/xml/System.Xml/XmlReader.xml index 30586e88de5..7ef5f62d7c3 100644 --- a/xml/System.Xml/XmlReader.xml +++ b/xml/System.Xml/XmlReader.xml @@ -4275,8 +4275,6 @@ An asynchronous method was called without For the asynchronous version of this method, see . - - ## Examples The following example reads an XML file and displays each of the nodes: @@ -4289,7 +4287,7 @@ An asynchronous method was called without **Output:** - [!INCLUDE [xmlreader-read-sample-output](~/includes/xmlreader-read-sample-output.md)] +[!INCLUDE[XmlReader Read output](~/includes/xmlreader-read-output.md)] ]]> diff --git a/xml/System/String.xml b/xml/System/String.xml index ec5c43a4640..173eb1cb44f 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -165,7 +165,15 @@ Characters in a string are represented by UTF-16 encoded code units, which corre Each character in a string has an associated Unicode character category, which is represented in .NET by the enumeration. The category of a character or a surrogate pair can be determined by calling the method. -[!INCLUDE[character-categories](~/includes/unicode-categories.md)] +.NET maintains its own table of characters and their corresponding categories, which ensures that a specific version of a .NET implementation running on different platforms returns identical character category information. On all .NET versions and across all OS platforms, character category information is provided by the [Unicode Character Database](https://www.unicode.org/ucd/). + +The following table lists .NET versions and the versions of the Unicode Standard on which their character categories are based. + +| .NET version | Version of the Unicode Standard | +|---------------|-----------------------------------------------------------------------------------------| +| .NET Core 2.1 | [The Unicode Standard, Version 8.0.0](https://www.unicode.org/versions/Unicode8.0.0/) | +| .NET Core 3.1 | [The Unicode Standard, Version 11.0.0](https://www.unicode.org/versions/Unicode11.0.0/) | +| .NET 5 | [The Unicode Standard, Version 13.0.0](https://www.unicode.org/versions/Unicode13.0.0/) | In addition, .NET supports string comparison and sorting based on the Unicode standard. String comparison and sorting information is provided by [International Components for Unicode](https://icu.unicode.org/) libraries (except on Windows versions prior to Windows 10 May 2019 Update). @@ -174,7 +182,6 @@ In addition, .NET supports string comparison and sorting based on the Unicode st In .NET, a object can include embedded null characters, which count as a part of the string's length. However, in some languages such as C and C++, a null character indicates the end of a string; it is not considered a part of the string and is not counted as part of the string's length. This means that the following common assumptions that C and C++ programmers or libraries written in C or C++ might make about strings are not necessarily valid when applied to objects: - The value returned by the `strlen` or `wcslen` functions does not necessarily equal . - - The string created by the `strcpy_s` or `wcscpy_s` functions is not necessarily identical to the string being copied. You should ensure that native C and C++ code that instantiates objects, and code that is passed objects through platform invoke, don't assume that an embedded null character marks the end of the string. @@ -284,14 +291,14 @@ Casing operations can be based on the rules of the current culture, a specified - Differences in case mappings between the invariant culture and all other cultures. In these cases, using the casing rules of the invariant culture to change a character to uppercase or lowercase returns the same character. For all other cultures, it returns a different character. Some of the affected characters are listed in the following table. - |Character|If changed to|Returns| - |---------------|-------------------|-------------| - |MICRON SIGN (U+00B5)|Uppercase|GREEK CAPITAL LETTER MU (U+-39C)| - |LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130)|Lowercase|LATIN SMALL LETTER I (U+0069)| - |LATIN SMALL LETTER DOTLESS I (U+0131)|Uppercase|LATIN CAPITAL LETTER I (U+0049)| - |LATIN SMALL LETTER LONG S (U+017F)|Uppercase|LATIN CAPITAL LETTER S (U+0053)| - |LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON (U+01C5)|Lowercase|LATIN SMALL LETTER DZ WITH CARON (U+01C6)| - |COMBINING GREEK YPOGEGRAMMENI (U+0345)|Uppercase|GREEK CAPITAL LETTER IOTA (U+0399)| + | Character | If changed to | Return value | + | ---------------------------------------------- | ------------- | -------------------------------- | + | MICRON SIGN (U+00B5) | Uppercase | GREEK CAPITAL LETTER MU (U+039C) | + | LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130) | Lowercase | LATIN SMALL LETTER I (U+0069) | + | LATIN SMALL LETTER DOTLESS I (U+0131) | Uppercase | LATIN CAPITAL LETTER I (U+0049) | + | LATIN SMALL LETTER LONG S (U+017F) | Uppercase | LATIN CAPITAL LETTER S (U+0053) | + | LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON (U+01C5) | Lowercase | LATIN SMALL LETTER DZ WITH CARON (U+01C6) | + | COMBINING GREEK YPOGEGRAMMENI (U+0345) | Uppercase | GREEK CAPITAL LETTER IOTA (U+0399) | - Differences in case mappings of two-letter mixed-case pairs in the ASCII character range. In most cultures, a two-letter mixed-case pair is equal to the equivalent two-letter uppercase or lowercase pair. This is not true for the following two-letter pairs in the following cultures, because in each case they are compared to a digraph: @@ -353,11 +360,8 @@ The following example illustrates the difference between culture-sensitive and o Use the following general guidelines to choose an appropriate sorting or string comparison method: - If you want the strings to be ordered based on the user's culture, you should order them based on the conventions of the current culture. If the user's culture changes, the order of sorted strings will also change accordingly. For example, a thesaurus application should always sort words based on the user's culture. - - If you want the strings to be ordered based on the conventions of a specific culture, you should order them by supplying a object that represents that culture to a comparison method. For example, in an application designed to teach students a particular language, you want strings to be ordered based on the conventions of one of the cultures that speaks that language. - - If you want the order of strings to remain unchanged across cultures, you should order them based on the conventions of the invariant culture or use an ordinal comparison. For example, you would use an ordinal sort to organize the names of files, processes, mutexes, or named pipes. - - For a comparison that involves a security decision (such as whether a username is valid), you should always perform an ordinal test for equality by calling an overload of the method. > [!NOTE] @@ -429,12 +433,9 @@ The Unicode standard defines a process called normalization that returns one bin An ordinal comparison is a binary comparison of the Unicode scalar value of corresponding objects in each string. The class includes a number of methods that can perform an ordinal comparison, including the following: - Any overload of the , , , , , and methods that includes a parameter. The method performs an ordinal comparison if you supply a value of or for this parameter. - - The overloads of the method. - - Methods that use ordinal comparison by default, such as , , and . - -- Methods that search for a value or for the elements in a array in a string instance. Such methods include and . +- Methods that search for a value or for the elements in a array in a string instance. Such methods include and . You can determine whether a string is normalized to normalization form C by calling the method, or you can call the method to determine whether a string is normalized to a specified normalization form. You can also call the method to convert a string to normalization form C, or you can call the method to convert a string to a specified normalization form. For step-by-step information about normalizing and comparing strings, see the and methods. @@ -455,9 +456,7 @@ The class provides members for comparing strings, testing s You can compare strings to determine their relative position in the sort order by using the following methods: - returns an integer that indicates the relationship of one string to a second string in the sort order. - - returns an integer that indicates the relationship of one string to a second string based on a comparison of their code points. - - returns an integer that indicates the relationship of the current string instance to a second string in the sort order. The method provides the and implementations for the class. ### Test strings for equality @@ -469,7 +468,6 @@ You call the method to determine whether two string The class includes two kinds of search methods: - Methods that return a value to indicate whether a particular substring is present in a string instance. These include the , , and methods. - - Methods that indicate the starting position of a substring in a string instance. These include the , , , and methods. > [!WARNING] @@ -480,23 +478,14 @@ The class includes two kinds of search methods: The class includes the following methods that appear to modify the value of a string: - inserts a string into the current instance. - - inserts one or more occurrences of a specified character at the beginning of a string. - - inserts one or more occurrences of a specified character at the end of a string. - - deletes a substring from the current instance. - - replaces a substring with another substring in the current instance. - - and convert all the characters in a string to lowercase. - - and convert all the characters in a string to uppercase. - - removes all occurrences of a character from the beginning and end of a string. - - removes all occurrences of a character from the end of a string. - - removes all occurrences of a character from the beginning of a string. > [!IMPORTANT] @@ -622,8 +611,8 @@ Here's a list of exceptions thrown by constructors that don't include pointer pa | Exception | Condition | Thrown by | |-----------|-----------|-----------| -||`value` is `null`.|| -||`startIndex`, `length`, or `count` is less than zero.

-or-

The sum of `startIndex` and `length` is greater than the number of elements in `value`.

-or-

`count` is less than zero.|

| +||`value` is `null`.|| +||`startIndex`, `length`, or `count` is less than zero.

-or-

The sum of `startIndex` and `length` is greater than the number of elements in `value`.

-or-

`count` is less than zero.|

| Here's a list of exceptions thrown by constructors that include pointer parameters. @@ -639,8 +628,8 @@ Here's a list of exceptions thrown by constructors that include pointer paramete | To | Call or use | |----|-------------| |Create a string.|Assignment from a string literal or an existing string ([Example 1: Use string assignment](#example-1-use-string-assignment))| -|Create a string from an entire character array.| ([Example 2: Use a character array](#example-2-use-a-character-array))| -|Create a string from a portion of a character array.| ([Example 3: Use a portion of a character array and repeating a single character](#example-3-use-a-portion-of-a-character-array-and-repeating-a-single-character))| +|Create a string from an entire character array.| ([Example 2: Use a character array](#example-2-use-a-character-array))| +|Create a string from a portion of a character array.| ([Example 3: Use a portion of a character array and repeating a single character](#example-3-use-a-portion-of-a-character-array-and-repeating-a-single-character))| |Create a string that repeats the same character multiple times.| ([Example 3: Use a portion of a character array and repeating a single character](#example-3-use-a-portion-of-a-character-array-and-repeating-a-single-character))| |Create a string from a pointer to a Unicode or wide character array.|| |Create a string from a portion of a Unicode or wide character array by using its pointer.|| @@ -651,7 +640,7 @@ Here's a list of exceptions thrown by constructors that include pointer paramete The most commonly used technique for creating strings programmatically is simple assignment, as illustrated in [Example 1](#example-1-use-string-assignment). The class also includes four types of constructor overloads that let you create strings from the following values: -- From a character array (an array of UTF-16-encoded characters). You can create a new object from the characters in the entire array or a portion of it. The constructor copies all the characters in the array to the new string. The constructor copies the characters from index `startIndex` to index `startIndex` + `length` - 1 to the new string. If `length` is zero, the value of the new string is . +- From a character array (an array of UTF-16-encoded characters). You can create a new object from the characters in the entire array or a portion of it. The constructor copies all the characters in the array to the new string. The constructor copies the characters from index `startIndex` to index `startIndex` + `length` - 1 to the new string. If `length` is zero, the value of the new string is . If your code repeatedly instantiates strings that have the same value, you can improve application performance by using an alternate means of creating strings. For more information, see [Handle repetitive strings](#handle-repetitive-strings). @@ -683,11 +672,11 @@ The most commonly used technique for creating strings programmatically is simple ## Handle repetitive strings -Apps that parse or decode streams of text often use the constructor or the method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead. +Apps that parse or decode streams of text often use the constructor or the method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead. For example, suppose you read and parse a stream of characters from a file that contains XML tags and attributes. When you parse the stream, you repeatedly encounter certain tokens (that is, sequences of characters that have a symbolic meaning). Tokens equivalent to the strings "0", "1", "true", and "false" are likely to occur frequently in an XML stream. -Instead of converting each token into a new string, you can create a object to hold commonly occurring strings. The object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the method to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the method to insert the token into the table and to get the corresponding string. +Instead of converting each token into a new string, you can create a object to hold commonly occurring strings. The object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the method to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the method to insert the token into the table and to get the corresponding string. ## Example 1: Use string assignment @@ -5751,8 +5740,8 @@ The following example is similar to the previous one, except that it left-aligns | Objective | Method to call | |-----------|----------------| -|Format one or more objects by using the conventions of the current culture.|Except for the overloads that include a `provider` parameter, the remaining overloads include a parameter followed by one or more object parameters. Because of this, you don't have to determine which overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| -|Format one or more objects by using the conventions of a specific culture.|Each overload that begins with a `provider` parameter is followed by a parameter and one or more object parameters. Because of this, you don't have to determine which specific overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| +|Format one or more objects by using the conventions of the current culture.|Except for the overloads that include a `provider` parameter, the remaining overloads include a parameter followed by one or more object parameters. Because of this, you don't have to determine which overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| +|Format one or more objects by using the conventions of a specific culture.|Each overload that begins with a `provider` parameter is followed by a parameter and one or more object parameters. Because of this, you don't have to determine which specific overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| |Perform a custom formatting operation either with an implementation or an implementation.|Any of the four overloads with a `provider` parameter. The compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list.| ## The Format method in brief @@ -5816,7 +5805,7 @@ Format items are processed sequentially from the beginning of the string. Each f - If the argument is `null`, the method inserts into the result string. You don't have to be concerned with handling a for null arguments. -- If you call the overload and the `provider` object's implementation returns a non-null implementation, the argument is passed to its method. If the format item includes a `formatString` argument, it is passed as the first argument to the method. If the implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes. +- If you call the overload and the `provider` object's implementation returns a non-null implementation, the argument is passed to its method. If the format item includes a `formatString` argument, it is passed as the first argument to the method. If the implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes. - If the argument implements the interface, its implementation is called. @@ -5862,7 +5851,7 @@ This example defines a format provider that formats an integer value as a custom This example defines a custom format provider that implements the and interfaces to do two things: -- It displays the parameters passed to its implementation. This enables us to see what parameters the method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application. +- It displays the parameters passed to its implementation. This enables us to see what parameters the method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application. - If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral. :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/interceptor2.cs" id="Snippet11"::: @@ -5938,7 +5927,7 @@ You can pad an integer or floating-point number with leading zeros to produce a ### How many items can I include in the format list? -There is no practical limit. The second parameter of the method is tagged with the attribute, which allows you to include either a delimited list or an object array as your format list. +There is no practical limit. The second parameter of the method is tagged with the attribute, which allows you to include either a delimited list or an object array as your format list. ### How do I include literal braces ("{" and "}") in the result string? @@ -5974,7 +5963,7 @@ For example, the following code throws a exception This is a problem of compiler overload resolution. Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the method. The exception is thrown because there are four format items but only a single item in the format list. -Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the method. The following example provides one implementation. +Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the method. The following example provides one implementation. :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa21.cs" id="Snippet22"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa21.fs" id="Snippet22"::: @@ -6063,7 +6052,7 @@ Because neither Visual Basic nor C# can convert an integer array to an object ar This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an expression to its string representation and to embed that representation in a string. -[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] ## Example: Formatting a single argument @@ -6167,7 +6156,7 @@ The index of a format item is not zero. This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of four or more expressions to their string representations and to embed those representations in a string. Since the `args` parameter is marked with the attribute, you can pass the objects to the method as individual arguments or as an array. -[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] ## Example: Format more than three arguments @@ -6335,7 +6324,7 @@ The index of a format item is less than zero, or greater than or equal to the le This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an expression to its string representation and to embed that representation in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts `arg0` to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] ]]> @@ -6432,11 +6421,11 @@ The index of a format item is not zero. This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert four or more expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] ### Example: Culture-sensitive formatting -This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. +This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. :::code language="csharp" source="~/snippets/csharp/System/String/Format/Example2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example2.fs" id="Snippet2"::: @@ -6727,7 +6716,7 @@ The index of a format item is less than zero, or greater than or equal to the le This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of two expressions to their string representations and to embed those representations in a string. -[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] ## Example: Format two arguments @@ -6833,7 +6822,7 @@ The index of a format item is not zero or one. This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert two expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] ]]> @@ -6924,7 +6913,7 @@ The index of a format item is not zero or one. This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of three expressions to their string representations and to embed those representations in a string. -[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] +[!INCLUDE[simple-string-format](~/includes/simple-string-format.md)] ## Example: Format three arguments @@ -7025,7 +7014,7 @@ The index of a format item is less than zero, or greater than two. This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert three expressions to their string representations and to embed those representations in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts each argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] +[!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] ]]> @@ -9882,10 +9871,11 @@ The following example uses the Sieve of Eratosthenes algorithm to calculate the ## Remarks If `separator` is `null` or if any element of `values` other than the first element is `null`, an empty string () is used instead. See the Notes for Callers section if the first element of `values` is `null`. - is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. + is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. ## Examples -The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. + +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to an integer array, which it then passes to the method. :::code language="csharp" source="~/snippets/csharp/System/String/Join/join1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join1.fs" id="Snippet1"::: @@ -13138,7 +13128,7 @@ This method is guaranteed O(n * r) complexity, where n is the length of is used to break a delimited string into substrings. You can use either a character array or a string array to specify zero or more delimiting characters or strings. If no delimiting characters are specified, the string is split at white-space characters. -Overloads of the method allow you to limit the number of substrings returned by the method (the method), to specify whether to include empty strings and/or trim substrings in the result (the and methods), or to do both (the and methods). +Overloads of the method allow you to limit the number of substrings returned by the method (the method), to specify whether to include empty strings and/or trim substrings in the result (the and methods), or to do both (the and methods). > [!TIP] > The method is not always the best way to break a delimited string into substrings. If you don't want to extract all of the substrings of a delimited string, or if you want to parse a string based on a pattern instead of a set of delimiter characters, consider using regular expressions, or combine one of the search methods that returns the index of a character with the method. For more information, see [Extract substrings from a string](/dotnet/standard/base-types/divide-up-strings). @@ -13232,7 +13222,7 @@ The sections for the individual overloads of `String.Split()` contain further ex ## Remarks -When a string is delimited by a known set of characters, you can use the method to separate it into substrings. +When a string is delimited by a known set of characters, you can use the method to separate it into substrings. Delimiter characters are not included in the elements of the returned array. For example, if the separator array includes the character "-" and the value of the current string instance is "aa-bb-cc", the method returns an array that contains three elements: "aa", "bb", and "cc". @@ -13273,9 +13263,9 @@ Because the `separator` parameter is decorated with the method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` array, and returns those substrings as elements of an array. +The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` array, and returns those substrings as elements of an array. -The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. ### Performance considerations @@ -13776,13 +13766,13 @@ In addition, if the same set of characters is used to split strings in multiple ## Examples -The following example illustrates the difference in the arrays returned by calling a string's method with its `options` parameter equal to and . +The following example illustrates the difference in the arrays returned by calling a string's method with its `options` parameter equal to and . :::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/system/string.split/options.vb" id="Snippet1"::: -The following example defines an array of separators that include punctuation and white-space characters. Passing this array along with a value of to the method returns an array that consists of the individual words from the string. +The following example defines an array of separators that include punctuation and white-space characters. Passing this array along with a value of to the method returns an array that consists of the individual words from the string. :::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet3"::: @@ -16130,7 +16120,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This method copies each character (that is, each object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. -To create a string from the characters in a character array, call the constructor. +To create a string from the characters in a character array, call the constructor. To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: @@ -16207,13 +16197,13 @@ The following example calls the method to extr constructor. +This method copies the characters in a portion of a string to a character array. To create a string from a range of characters in a character array, call the constructor. The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. -To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: +To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: |Encoding|Object| |--------------|------------| @@ -16462,7 +16452,7 @@ If your application depends on the case of a string changing in a predictable wa If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. ## Examples -The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. +The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. :::code language="csharp" source="~/snippets/csharp/System/String/ToLowerInvariant/tolowerinvariant.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/ToLowerInvariant/tolowerinvariant.fs" id="Snippet1"::: @@ -16835,7 +16825,7 @@ If you need the lowercase or uppercase version of an operating system identifier method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. +The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. :::code language="csharp" source="~/snippets/csharp/System/String/ToUpperInvariant/toupperinvariant.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpperInvariant/toupperinvariant.fs" id="Snippet1":::