diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index 51f53f09ca4..4c3bba07e5d 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -512,9 +512,9 @@ You use this constructor when you want to specify whether compression efficiency > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . +Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. @@ -522,7 +522,7 @@ Multiple simultaneous asynchronous requests render the request completion order Use the property to determine whether the current object supports reading. -If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . ]]> @@ -608,9 +608,9 @@ If a stream is closed or you pass an invalid argument, exceptions are thrown imm method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. +Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. If a stream is writable, writing at the end of the stream expands the stream. @@ -618,7 +618,7 @@ The current position in the stream is updated when you issue the asynchronous re Use the property to determine whether the current object supports writing. -If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . ]]> @@ -918,7 +918,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks -This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. +This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -1028,9 +1028,9 @@ Calling `DisposeAsync` allows the resources used by the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . +Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . This method blocks until the I/O operation has completed. @@ -1094,11 +1094,11 @@ The stream is . ## Remarks -Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). - must be called only once for every call to the method. + must be called only once for every call to the method. -This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to . Exceptions thrown by the thread pool thread will not be visible when calling . +This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to . Exceptions thrown by the thread pool thread will not be visible when calling . ]]> @@ -1344,7 +1344,7 @@ This method stores in the task it returns all non-usage exceptions that the meth > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1415,7 +1415,7 @@ Use for reading primitive data types. > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -The following example shows how to compress and decompress bytes by using the and methods. +The following example shows how to compress and decompress bytes by using the and methods. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/MemoryWriteReadExample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO.Compression/Deflate/MemoryWriteReadExample.fs" id="Snippet1"::: @@ -1745,7 +1745,7 @@ Use the property to determine property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the Deflate stream advances by the number of bytes written. If an exception occurs, the position within the Deflate stream remains unchanged. @@ -1810,7 +1810,7 @@ If the write operation is successful, the position within the Deflate stream adv and methods. +The following example shows how to compress and decompress bytes by using the and methods. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/Deflate/MemoryWriteReadExample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO.Compression/Deflate/MemoryWriteReadExample.fs" id="Snippet1"::: diff --git a/xml/System.IO.Compression/GZipStream.xml b/xml/System.IO.Compression/GZipStream.xml index c67e2aa4c2f..f9abc3fb04a 100644 --- a/xml/System.IO.Compression/GZipStream.xml +++ b/xml/System.IO.Compression/GZipStream.xml @@ -140,7 +140,7 @@ The following example shows how to use the class. -This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. +This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. ]]> @@ -283,7 +283,7 @@ The following example shows how to set the compression mode when creating a class, and whether to leave the stream object open after disposing the object. -This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. +This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. ## Examples @@ -529,9 +529,9 @@ By default, the compression level is set to [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous file I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous file I/O](/dotnet/standard/io/asynchronous-file-i-o). -Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . +Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. @@ -539,7 +539,7 @@ Multiple simultaneous asynchronous requests render the request completion order Use the property to determine whether the current object supports reading. -If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . ]]> The method tried to read asynchronously past the end of the stream, or a disk error occurred. @@ -626,11 +626,11 @@ If a stream is closed or you pass an invalid argument, exceptions are thrown imm ## Remarks -Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -The method starts an asynchronous write operation to a stream object. +The method starts an asynchronous write operation to a stream object. -You must create a callback method that implements the delegate and pass its name to the method. +You must create a callback method that implements the delegate and pass its name to the method. ]]> @@ -877,7 +877,7 @@ Copying begins at the current position in the current GZip stream, and does not ## Remarks -The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. +The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -939,7 +939,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks -This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. +This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -1049,9 +1049,9 @@ Calling `DisposeAsync` allows the resources used by the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . +Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . This method blocks until the I/O operation has completed. @@ -1110,9 +1110,9 @@ This method blocks until the I/O operation has completed. ## Remarks -Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). +Starting with .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). -The method completes the asynchronous write operation started in the method. +The method completes the asynchronous write operation started in the method. ]]> @@ -1357,7 +1357,7 @@ This method stores in the task it returns all non-usage exceptions that the meth > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method reads a maximum of `buffer.Length` bytes from the current stream and stores them in `buffer`. The current position within the GZip stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the GZip stream remains unchanged. In the event that no data is available, this method blocks until at least one byte of data can be read. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1434,7 +1434,7 @@ If data is found in an invalid format, an ## Examples -The following example shows how to compress and decompress bytes by using the and methods. +The following example shows how to compress and decompress bytes by using the and methods. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/GZip/MemoryWriteReadExample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO.Compression/GZip/MemoryWriteReadExample.fs" id="Snippet1"::: @@ -1768,7 +1768,7 @@ Use the property to determine wh ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the GZip stream advances by the number of bytes written. If an exception occurs, the position within the GZip stream remains unchanged. @@ -1835,11 +1835,11 @@ If the write operation is successful, the position within the GZip stream advanc ## Remarks -The write operation might not occur immediately but is buffered until the buffer size is reached or until the or method is called. +The write operation might not occur immediately but is buffered until the buffer size is reached or until the or method is called. ## Examples -The following example shows how to compress and decompress bytes by using the and methods. +The following example shows how to compress and decompress bytes by using the and methods. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/GZip/MemoryWriteReadExample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO.Compression/GZip/MemoryWriteReadExample.fs" id="Snippet1"::: diff --git a/xml/System.IO.Compression/ZipArchive.xml b/xml/System.IO.Compression/ZipArchive.xml index 65b273937d5..bc4e4b01bfe 100644 --- a/xml/System.IO.Compression/ZipArchive.xml +++ b/xml/System.IO.Compression/ZipArchive.xml @@ -503,7 +503,7 @@ If the comment byte length is larger than , it will ## Remarks The `entryName` string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified path and name already exists in the archive, a second entry is created with the same path and name. - The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. + The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. ## Examples The following example shows how to create an entry and write to it by using a stream. @@ -640,11 +640,11 @@ If the comment byte length is larger than , it will object. Unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to `true`, all underlying streams are closed and no longer available for subsequent write operations. + This method finishes writing the archive and releases all resources used by the object. Unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to `true`, all underlying streams are closed and no longer available for subsequent write operations. When you are finished using this instance of , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. - calls the method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). + calls the method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). ]]> @@ -692,15 +692,15 @@ If the comment byte length is larger than , it will constructor overload and set its `leaveOpen` parameter to `true`. + If `disposing` is set to `true`, all underlying streams are closed and no longer available for subsequent write operations, unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to `true`. This method is called only by the public and methods; do not call this method directly. - When you implement the dispose pattern, the Boolean parameter of the method should be used as follows: + When you implement the dispose pattern, the Boolean parameter of the method should be used as follows: -- The method of the current object should call with the Boolean parameter set to `true` to release both managed and unmanaged resources. +- The method of the current object should call with the Boolean parameter set to `true` to release both managed and unmanaged resources. -- The method of the current object should call with the Boolean parameter set to `false` to release only unmanaged resources. +- The method of the current object should call with the Boolean parameter set to `false` to release only unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). @@ -801,7 +801,7 @@ If the comment byte length is larger than , it will property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. + Use the property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. ## Examples The following example shows how to open a zip archive and iterate through the collection of entries. @@ -863,7 +863,7 @@ If the comment byte length is larger than , it will If multiple entries that have the specified name exist in the archive, the first one is returned. The name of the entry is compared to `entryName` using ordinal comparison. ## Examples - The following example shows how to use the method to retrieve an entry. + The following example shows how to use the method to retrieve an entry. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO.Compression/ZipArchive/GetEntry/program2.fs" id="Snippet2"::: @@ -918,7 +918,7 @@ If the comment byte length is larger than , it will property when you create an instance of the class. Use the or constructor to provide a value for the property. + You specify a value for the property when you create an instance of the class. Use the or constructor to provide a value for the property. ]]> diff --git a/xml/System.IO.Compression/ZipArchiveEntry.xml b/xml/System.IO.Compression/ZipArchiveEntry.xml index 121530f9b44..19511a08708 100644 --- a/xml/System.IO.Compression/ZipArchiveEntry.xml +++ b/xml/System.IO.Compression/ZipArchiveEntry.xml @@ -172,7 +172,7 @@ If the comment byte length is larger than , it will This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. ## Examples - The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: @@ -488,7 +488,7 @@ If the comment byte length is larger than , it will This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. ## Examples - The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: @@ -583,7 +583,7 @@ If the comment byte length is larger than , it will You use this method to access the stream for an entry in a zip archive. After retrieving the stream, you can read from or write to the stream. When you write to the stream, the modifications you make to the entry will appear in the zip archive. ## Examples - The following example shows how to create a new entry, open it with the method, and write to the stream. + The following example shows how to create a new entry, open it with the method, and write to the 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"::: diff --git a/xml/System.IO.Compression/ZipFile.xml b/xml/System.IO.Compression/ZipFile.xml index c1c7354a2c1..9ddd22f9f1d 100644 --- a/xml/System.IO.Compression/ZipFile.xml +++ b/xml/System.IO.Compression/ZipFile.xml @@ -171,7 +171,7 @@ An I/O error occurred while opening a file to be archived. method overload. + The directory structure from the file system is preserved in the archive. If the directory is empty, an empty archive is created. This method overload does not include the base directory in the archive and does not allow you to specify a compression level. If you want to include the base directory or specify a compression level, call the method overload. If the archive already exists, an exception is thrown. If an entry with the specified name already exists in the archive, a second entry is created with an identical name. @@ -2509,7 +2509,7 @@ An archive entry has been compressed using a compression method that isn't suppo , the archive is opened with from the enumeration 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 from the enumeration 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. @@ -2899,7 +2899,7 @@ An unspecified I/O error occurred while opening the file. method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. +This method is equivalent to calling the method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. ## Examples diff --git a/xml/System.IO.Compression/ZipFileExtensions.xml b/xml/System.IO.Compression/ZipFileExtensions.xml index 31e6457ad5f..a7d33606ef5 100644 --- a/xml/System.IO.Compression/ZipFileExtensions.xml +++ b/xml/System.IO.Compression/ZipFileExtensions.xml @@ -748,11 +748,11 @@ A has been compressed usi exception. To overwrite an existing file, use the method overload instead. + If the destination file already exists, this method does not overwrite it; it throws an exception. To overwrite an existing file, use the method overload instead. The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. - You cannot use this method to extract a directory; use the method instead. + You cannot use this method to extract a directory; use the method instead. ## Examples The following example shows how to iterate through the contents of a zip archive file and extract files that have a .txt extension. @@ -854,7 +854,7 @@ A has been compressed usi ## Remarks The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. - You cannot use this method to extract a directory; use the method instead. + You cannot use this method to extract a directory; use the method instead. ## Examples The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. diff --git a/xml/System.IO.IsolatedStorage/INormalizeForIsolatedStorage.xml b/xml/System.IO.IsolatedStorage/INormalizeForIsolatedStorage.xml index 95447f532a7..275fe5a63de 100644 --- a/xml/System.IO.IsolatedStorage/INormalizeForIsolatedStorage.xml +++ b/xml/System.IO.IsolatedStorage/INormalizeForIsolatedStorage.xml @@ -50,11 +50,11 @@ Enables comparisons between an isolated store and an application domain and assembly's evidence. - . For evidence that implements this interface, the method is called and comparisons are based on the normalized copy of the object returned by that method. - + . For evidence that implements this interface, the method is called and comparisons are based on the normalized copy of the object returned by that method. + ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml index c75e370b10a..ed1eb1e253b 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml @@ -330,7 +330,7 @@ implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. + This property represents the total usage of all storage resources within the isolated storage scope. implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. ]]> @@ -479,7 +479,7 @@ method overrides this method. + The method overrides this method. ]]> @@ -676,9 +676,9 @@ property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. + The default implementation of the property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. - You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. + You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. ]]> @@ -782,7 +782,7 @@ implements this method. + implements this method. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml index f34421fc316..0b1ff71430f 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml @@ -73,7 +73,7 @@ - Invalid operations. Some operations are not supported for isolated storage. - For a list of initial property values for an instance of `IsolatedStorageException`, see the constructors. + For a list of initial property values for an instance of `IsolatedStorageException`, see the constructors. ]]> @@ -135,8 +135,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The localized error message string.| +||`null`.| +||The localized error message string.| ]]> @@ -191,8 +191,8 @@ |Property|Value| |--------------|-----------| -||`null`.| -||The error message string.| +||`null`.| +||The error message string.| ]]> @@ -316,8 +316,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml index c0aadf17c58..17ce32ded26 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml @@ -74,7 +74,7 @@ For more information, see [Isolated Storage](/dotnet/standard/io/isolated-storage). - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. > [!IMPORTANT] > Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. @@ -82,7 +82,7 @@ ## Examples - The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated by user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is then called to create directories, and two instances of the class create files in these directories. + The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated by user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is then called to create directories, and two instances of the class create files in these directories. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Overview/source.vb" id="Snippet1"::: @@ -199,7 +199,7 @@ method. For the complete context of this example, see the overview. + The following code example demonstrates how to use the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet10"::: @@ -272,7 +272,7 @@ method overload to overwrite an existing file. + `sourceFileName` and `destinationFileName` must specify different file names. Use the method overload to overwrite an existing file. ]]> @@ -441,12 +441,12 @@ method returns without creating a new directory. The [How to: Create Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-create-files-and-directories-in-isolated-storage) example demonstrates the use of the method + The created directory initially contains no files. If the directory already exists, the method returns without creating a new directory. The [How to: Create Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-create-files-and-directories-in-isolated-storage) example demonstrates the use of the method ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet7"::: @@ -510,7 +510,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -657,7 +657,7 @@ ## Remarks A directory must be empty before it is deleted. The deleted directory cannot be recovered once deleted. - The [How to: Delete Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-delete-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + The [How to: Delete Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-delete-files-and-directories-in-isolated-storage) example demonstrates the use of the method. @@ -727,12 +727,12 @@ ## Remarks The deleted file cannot be recovered once deleted. - The [How to: Delete Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-delete-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + The [How to: Delete Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-delete-files-and-directories-in-isolated-storage) example demonstrates the use of the method. ## Examples - The following code example uses the method to delete a number of files in isolated storage. + The following code example uses the method to delete a number of files in isolated storage. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet6"::: @@ -860,12 +860,12 @@ Call `Dispose` when you are finished using the . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that was occupying. > [!NOTE] -> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. +> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. ## Examples - The following code example opens an isolated storage file, uses it to write information to a stream, closes the file, and then uses the method to release all resources. + The following code example opens an isolated storage file, uses it to write information to a stream, closes the file, and then uses the method to release all resources. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet10"::: @@ -1107,7 +1107,7 @@ method with "*" specified for the search pattern. + This method is equivalent to using the method with "*" specified for the search pattern. ]]> @@ -1177,14 +1177,14 @@ The `searchPattern` "Project\Data*" will give all subdirectories of Project beginning with Data in the isolated storage scope. The `searchPattern` "\*" will return all directories located in the root. For complete description of search string criteria, see the class. - For information on getting file names, see the method. + For information on getting file names, see the method. - The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet16"::: @@ -1254,7 +1254,7 @@ method. + The [How to: Enumerate Stores for Isolated Storage](/dotnet/standard/io/how-to-enumerate-stores-for-isolated-storage) example demonstrates the use of the method. ]]> @@ -1320,7 +1320,7 @@ method with "*" specified for the search pattern. + This method is equivalent to using the method with "*" specified for the search pattern. ]]> @@ -1386,14 +1386,14 @@ ## Remarks The `searchPattern` "Project\Data*.txt" will give all ".txt" files beginning with Data in the Project directory of the isolated storage scope. For complete description of search pattern strings, see . - For information about how to find directory names, see the method. + For information about how to find directory names, see the method. - The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet16"::: @@ -1607,7 +1607,7 @@ ## Remarks All assemblies associated with an application use the same isolated store when using this method. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet18"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet18"::: @@ -1678,7 +1678,7 @@ ## Remarks The same assembly within different applications always uses the same isolated store when using this method. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet19"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet19"::: @@ -1744,7 +1744,7 @@ ## Remarks The same assembly code will use different isolated stores when used in the context of different applications. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet20"::: @@ -1752,12 +1752,12 @@ Different assemblies running within the same application domain always have distinct isolated stores. > [!NOTE] -> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . +> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet10"::: @@ -1888,7 +1888,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -1978,7 +1978,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -2071,7 +2071,7 @@ This form of `GetStore` is most useful for administrative code that needs to open a store as if it were another assembly. The store is opened for the evidence provided and not for the currently executing assembly. > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -2165,17 +2165,17 @@ most likely to be called from application code. + This is the overload of most likely to be called from application code. - This overload of opens an isolated store for the evidence types that are passed in. + This overload of opens an isolated store for the evidence types that are passed in. > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet15"::: @@ -2257,7 +2257,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . @@ -2343,7 +2343,7 @@ ## Remarks All assemblies associated with an application use the same isolated store when using this method. This method can be used only when the application identity can be determined - for example, when the application is published through ClickOnce deployment or is a Silverlight-based application. If you attempt to use this method outside a ClickOnce or Silverlight-based application, you will receive an exception, because the application identity of the caller cannot be determined. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet21"::: @@ -2417,7 +2417,7 @@ ## Remarks The same assembly within different applications always uses the same isolated store when using this method. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet22"::: @@ -2488,7 +2488,7 @@ ## Remarks The same assembly code will use different isolated stores when used in the context of different applications. - is functionally equivalent to the following code: + is functionally equivalent to the following code: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.vb" id="Snippet23"::: @@ -2496,12 +2496,12 @@ Different assemblies running within the same application domain always have distinct isolated stores. > [!NOTE] -> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . +> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . ## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. + The following code example demonstrates the method. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet10"::: @@ -2640,15 +2640,15 @@ method enables an application to explicitly request a larger quota size in bytes. The new quota size must not be smaller than the current quota size, because only quota increases are allowed. + The method enables an application to explicitly request a larger quota size in bytes. The new quota size must not be smaller than the current quota size, because only quota increases are allowed. - Whenever the method is called, isolated storage calls the method. + Whenever the method is called, isolated storage calls the method. - You can implement policy decisions by creating a custom object that overrides the method so that the object can perform policy decisions based on a object. + You can implement policy decisions by creating a custom object that overrides the method so that the object can perform policy decisions based on a object. - If there is no custom object, the quota increase request is denied, because the default implementation for returns `false`. + If there is no custom object, the quota increase request is denied, because the default implementation for returns `false`. - Currently, none of the hosts in the .NET Framework provide this customization, so always returns `false`. + Currently, none of the hosts in the .NET Framework provide this customization, so always returns `false`. ]]> @@ -3020,7 +3020,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -3095,7 +3095,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -3172,7 +3172,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -3320,7 +3320,7 @@ ## Examples - The following code example uses the method to delete the isolated storage file after its contents have been emptied. The [How to: Delete Stores in Isolated Storage](/dotnet/standard/io/how-to-delete-stores-in-isolated-storage) example also demonstrates the use of the method. + The following code example uses the method to delete the isolated storage file after its contents have been emptied. The [How to: Delete Stores in Isolated Storage](/dotnet/standard/io/how-to-delete-stores-in-isolated-storage) example also demonstrates the use of the method. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet16"::: diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml index b79c5da29a9..ae9b5d5fec7 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml @@ -70,7 +70,7 @@ Since this class extends , you can use an instance of in most situations where a might otherwise be used, such as to construct a or . - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. > [!IMPORTANT] > Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. @@ -758,7 +758,7 @@ ## Remarks The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. - You must call with this to find out how many bytes were read. + You must call with this to find out how many bytes were read. ]]> @@ -851,7 +851,7 @@ The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. - You must call with the object that this method returns to find out how many bytes were written. + You must call with the object that this method returns to find out how many bytes were written. ]]> @@ -908,7 +908,7 @@ ## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet11"::: @@ -1018,7 +1018,7 @@ ## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet13"::: @@ -1056,14 +1056,14 @@ ## Remarks -Any data previously written to the buffer is copied to the file before the file stream is closed, so it is not necessary to call before invoking Close. +Any data previously written to the buffer is copied to the file before the file stream is closed, so it is not necessary to call before invoking Close. Following a call to Close, any operations on the file stream might raise exceptions. After `Close` has been called once, it does nothing if called again. The method invokes Close so the file stream is closed before the garbage collector finalizes the object. objects require an object that determines the storage context for the files accessed. For streams opened without passing an object, a default object is created for the executing assembly and then closed during the call to Close. > [!NOTE] -> The `Close` method calls with disposing set to true to release its resources, then calls to suppress finalization of this object by the garbage collector. +> The `Close` method calls with disposing set to true to release its resources, then calls to suppress finalization of this object by the garbage collector. ## Examples @@ -1158,9 +1158,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. - When the `disposing` parameter is true, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + When the `disposing` parameter is true, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. ]]> @@ -1256,7 +1256,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) must be called exactly once on every object from , and calling is the only way to know how many bytes were read from the . will block until the I/O operation has completed. + must be called exactly once on every object from , and calling is the only way to know how many bytes were read from the . will block until the I/O operation has completed. ]]> @@ -1309,9 +1309,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) must be called exactly once on every from . + must be called exactly once on every from . - will block until the I/O operation has completed. + will block until the I/O operation has completed. ]]> @@ -1372,9 +1372,9 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) performs two functions. First, any data previously written to the buffer is copied to the file and the buffer is cleared. Second, if is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. + Because a buffer can be used for either reading or writing, but not both simultaneously, performs two functions. First, any data previously written to the buffer is copied to the file and the buffer is cleared. Second, if is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. - Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. + Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. ]]> @@ -1533,7 +1533,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) . + For more information, see . ]]> @@ -1584,7 +1584,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) objects cannot be created, unlike . However, the , , , and methods are supported on synchronous instances, with some performance penalties. + Asynchronous objects cannot be created, unlike . However, the , , , and methods are supported on synchronous instances, with some performance penalties. @@ -1643,7 +1643,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) represents the number of bytes currently in the file. It is not affected by isolated storage quota. + represents the number of bytes currently in the file. It is not affected by isolated storage quota. @@ -1874,9 +1874,9 @@ The `buffer` parameter can be an instance of the class, or If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. -The method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`. +The method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`. -The method will return zero only if the end of the stream is reached. In all other cases, always reads at least one byte from the stream before returning. If no data is available from the object upon a call to , the method will block until at least one byte of data can be returned. +The method will return zero only if the end of the stream is reached. In all other cases, always reads at least one byte from the stream before returning. If no data is available from the object upon a call to , the method will block until at least one byte of data can be returned. ]]> @@ -1974,9 +1974,9 @@ The `buffer` parameter can be an instance of the class, or If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. -The method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`. +The method treats the `buffer` parameter as a block of bytes, regardless of its actual type. Likewise, the `offset` and `count` parameters are always specified in bytes. For `buffer` parameters other than byte arrays, this means that an element index or the number of elements must be multiplied by the element size in bytes to form a correct value for `offset` or `count`. -The method will return zero only if the end of the stream is reached. In all other cases, always reads at least one byte from the stream before returning. If no data is available from the object upon a call to , the method will block until at least one byte of data can be returned. +The method will return zero only if the end of the stream is reached. In all other cases, always reads at least one byte from the stream before returning. If no data is available from the object upon a call to , the method will block until at least one byte of data can be returned. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -2030,7 +2030,7 @@ This method stores in the task it returns all non-usage exceptions that the meth method can be used to read data from an object. For the complete context of this example, see the overview. + The following code example demonstrates how the method can be used to read data from an object. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet14"::: @@ -2524,7 +2524,7 @@ This method stores in the task it returns all non-usage exceptions that the meth method can be used to read data from an object. For the complete context of this example, see the overview. + The following code example demonstrates how the method can be used to read data from an object. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet14"::: diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageScope.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageScope.xml index 050f8ec2063..0d718768942 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageScope.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageScope.xml @@ -68,8 +68,8 @@ ## Examples - The following code example demonstrates how the enumeration is used in the methods. - + The following code example demonstrates how the enumeration is used in the methods. + :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet15"::: diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml index 34b8fe53765..a46e7351451 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml @@ -21,7 +21,7 @@ ## Remarks The property gets this enumeration to determine which operations can be performed in isolated storage. - A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. + A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml index a2514fa84d9..84252b03c8b 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml @@ -23,11 +23,11 @@ Provides settings for maintaining the quota size for isolated storage. - method. - + method. + ]]> @@ -79,11 +79,11 @@ Gets the option for managing isolated storage security. The option to increase the isolated quota storage size. - enumeration value, which is the only value in the enumeration. - + enumeration value, which is the only value in the enumeration. + ]]> diff --git a/xml/System.IO.Log/FileRecordSequence.xml b/xml/System.IO.Log/FileRecordSequence.xml index 8318c2ef7f9..6308b8d3483 100644 --- a/xml/System.IO.Log/FileRecordSequence.xml +++ b/xml/System.IO.Log/FileRecordSequence.xml @@ -24,21 +24,21 @@ Implements an on top of a file. This class cannot be inherited. - is a record sequence based on a single log file in the file system. It is a simple implementation of the interface, on top of a simple file-based log. - - To manipulate a file-based log, the account that your application is running in must have sufficient privileges, as dictated by the file system security at the time the is constructed. In addition, a demand for FullTrust is made at construction time. The permission verification results are cached thereafter in keeping with the Windows security model. You should ensure that you do not accidentally expose the contents of the record sequence to an unauthorized user. - - - -## Examples - The following example creates a record sequence, appends record to it, and finally reads the records. - + is a record sequence based on a single log file in the file system. It is a simple implementation of the interface, on top of a simple file-based log. + + To manipulate a file-based log, the account that your application is running in must have sufficient privileges, as dictated by the file system security at the time the is constructed. In addition, a demand for FullTrust is made at construction time. The permission verification results are cached thereafter in keeping with the Windows security model. You should ensure that you do not accidentally expose the contents of the record sequence to an unauthorized user. + + + +## Examples + The following example creates a record sequence, appends record to it, and finally reads the records. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/irecordsequence/cs/readrecord.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet1"::: + ]]> @@ -72,19 +72,19 @@ A relative or absolute path for the file that this instance will encapsulate. Initializes a new instance of the class with a specified file. - instance has been disposed of, but read attempts will succeed. If `path` is not found, a new file is created with a size of 0 bytes. - - - -## Examples - The following example creates a record sequence, appends record to it, reads the records, and finally disposes the sequence. - + instance has been disposed of, but read attempts will succeed. If `path` is not found, a new file is created with a size of 0 bytes. + + + +## Examples + The following example creates a record sequence, appends record to it, reads the records, and finally disposes the sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/irecordsequence/cs/readrecord.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet1"::: + ]]> The file specified by is not valid. @@ -198,14 +198,14 @@ Writes a log record to the . - @@ -243,20 +243,20 @@ Writes a log record to the . This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - - - -## Examples - The following example creates a record sequence, appends record to it, and finally reads the records. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/filerecordsequence/cs/filerecordsequence.cs" id="Snippet0"::: - + flag using the `recordAppendOptions` parameter, or call the method. + + + +## Examples + The following example creates a record sequence, appends record to it, and finally reads the records. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/filerecordsequence/cs/filerecordsequence.cs" id="Snippet0"::: + ]]> One or more of the arguments are . @@ -301,21 +301,21 @@ Writes a log record to the . This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - - - -## Examples - The following example shows how you can create a record sequence with this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/irecordsequence/cs/readrecord.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet3"::: - + flag using the `recordAppendOptions` parameter, or call the method. + + + +## Examples + The following example shows how you can create a record sequence with this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/irecordsequence/cs/readrecord.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet3"::: + ]]> One or more of the arguments are . @@ -362,15 +362,15 @@ Writes a log record to the , using space previously reserved in the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -420,15 +420,15 @@ Writes a log record to the , using space previously reserved in the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -466,21 +466,21 @@ Gets the sequence number of the first valid record in the current . The lowest sequence number that corresponds to a valid record in the . - and less than . All other sequence numbers are invalid. - - The value of this property can be changed by calling the or method. - - - -## Examples - The following example shows using in a loop: - + and less than . All other sequence numbers are invalid. + + The value of this property can be changed by calling the or method. + + + +## Examples + The following example shows using in a loop: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/irecordsequence/cs/readrecord.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/irecordsequence/vb/readrecord.vb" id="Snippet2"::: + ]]> The property was accessed after the sequence has been disposed of. @@ -532,15 +532,15 @@ Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -589,15 +589,15 @@ Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -648,17 +648,17 @@ Begins an asynchronous append operation using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -712,17 +712,17 @@ Begins an asynchronous append operation using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -768,19 +768,19 @@ Begins an asynchronous flush operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous flush operation, which could still be pending. - returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. - - Calling this method ensures that all records that have been appended to the are durably written. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. + + Calling this method ensures that all records that have been appended to the are durably written. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> - One or more of the arguments is invalid. - + One or more of the arguments is invalid. + is not valid for this sequence. is not between the base and last sequence numbers of this sequence. @@ -839,19 +839,19 @@ Begins an asynchronous reserve and append operation. This method cannot be inherited. An that represents this asynchronous operation, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. + + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . @@ -907,19 +907,19 @@ Begins an asynchronous reserve and append operation. This method cannot be inherited. An that represents this asynchronous operation, which could still be pending. - returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method, to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. + + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . @@ -978,33 +978,33 @@ Begins an asynchronous restart area write operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous restart area write operation, which could still be pending. - returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. - was not created by this record sequence. - - -or- - + was not created by this record sequence. + + -or- + is not valid for this sequence. The operation cannot be performed because the record sequence was opened with read-only access. The request cannot be performed because of an unexpected I/O exception. @@ -1049,33 +1049,33 @@ Begins an asynchronous restart area write operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous restart area write operation, which could still be pending. - returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. - was not created by this record sequence. - - -or- - + was not created by this record sequence. + + -or- + is not valid for this sequence. The operation cannot be performed because the record sequence was opened with read-only access. The request cannot be performed because of an unexpected I/O exception. @@ -1167,13 +1167,13 @@ Ends an asynchronous append operation. This method cannot be inherited. The sequence number of the appended log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1212,13 +1212,13 @@ Ends an asynchronous flush operation. This method cannot be inherited. The sequence number of the last record written. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1257,13 +1257,13 @@ Ends an asynchronous reserve and append operation. This method cannot be inherited. The sequence number of the appended log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1302,13 +1302,13 @@ Ends an asynchronous restart area write operation. This method cannot be inherited. The sequence number of the written log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1353,11 +1353,11 @@ Ensures that all appended records have been written. This method cannot be inherited. The sequence number of the last record written. - have been durably written. - + have been durably written. + ]]> An I/O error occurred while flushing the data. @@ -1392,11 +1392,11 @@ Ensures that all appended records have been written. This method cannot be inherited. The sequence number of the last record written. - @@ -1431,11 +1431,11 @@ Gets the sequence number which is greater than the last record appended. A sequence number which is greater than the last record appended. - and less than . All other sequence numbers are invalid. - + and less than . All other sequence numbers are invalid. + ]]> The property was accessed after the sequence has been disposed of. @@ -1496,32 +1496,32 @@ Returns an enumerable collection of records in the sequence. This method cannot be inherited. An enumerable collection of records in the sequence. - One or more of the arguments are out of range. The operation cannot be performed because the record sequence was opened with write-only access. - The record sequence is corrupted. - - -or- - + The record sequence is corrupted. + + -or- + The record was written with an incompatible version of the record sequence. - The enumeration has ended. - - -or- - + The enumeration has ended. + + -or- + The enumeration has not been started. A call to must be made. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -1551,23 +1551,23 @@ Returns an enumerable collection of the restart areas in the sequence. This method cannot be inherited. An enumerable collection of the restart areas in the sequence. - The operation cannot be performed because the record sequence was opened with write-only access. - The record sequence is corrupted. - - -or- - + The record sequence is corrupted. + + -or- + The record was written with an incompatible version of the record sequence. - The enumeration has ended. - - -or- - + The enumeration has ended. + + -or- + The enumeration has not been started. A call to must be made. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -1626,15 +1626,15 @@ Automatically makes a single reservation and appends a record to the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -1692,15 +1692,15 @@ Automatically makes a single reservation and appends a record to the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments are . @@ -1763,11 +1763,11 @@ Gets the sequence number of the most recently written restart area. The sequence number of the most recently written restart area. - The property was accessed after the sequence has been disposed of. @@ -1797,11 +1797,11 @@ if appends are automatically retried if the log is full; otherwise, . The default is . - call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. - + call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. + ]]> The property was accessed after the sequence has been disposed of. @@ -1830,11 +1830,11 @@ Occurs when the record sequence determines that the tail must be moved forward. This method cannot be inherited. - @@ -1847,13 +1847,13 @@ Writes a restart area to the . - method. - + method. + ]]> @@ -1885,15 +1885,15 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - + method. + + The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + ]]> One or more of the arguments are . @@ -1931,15 +1931,15 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - + method. + + The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + ]]> One or more of the arguments are . @@ -1979,25 +1979,25 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. is not valid for this sequence. @@ -2037,25 +2037,25 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. is not valid for this sequence. @@ -2097,35 +2097,35 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. - was not created by this record sequence. - - -or- - + was not created by this record sequence. + + -or- + is not valid for this sequence. The operation cannot be performed because the record sequence was opened with read-only access. The request cannot be performed because of an unexpected I/O exception. @@ -2166,35 +2166,35 @@ Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments are . - is not between the base and last sequence numbers of this sequence. - - -or- - + is not between the base and last sequence numbers of this sequence. + + -or- + A new or existing archive tail or base of the active log is invalid. - was not created by this record sequence. - - -or- - + was not created by this record sequence. + + -or- + is not valid for this sequence. The operation cannot be performed because the record sequence was opened with read-only access. The request cannot be performed because of an unexpected I/O exception. diff --git a/xml/System.IO.Log/FileRegion.xml b/xml/System.IO.Log/FileRegion.xml index 42d624f53cd..0c587082a54 100644 --- a/xml/System.IO.Log/FileRegion.xml +++ b/xml/System.IO.Log/FileRegion.xml @@ -57,7 +57,7 @@ property of the stream returned by the method. + This property returns the length of the entire file instead of that of a single region in the file. The length of the region in the file can be found by examining the property of the stream returned by the method. diff --git a/xml/System.IO.Log/IRecordSequence.xml b/xml/System.IO.Log/IRecordSequence.xml index 54611c150fc..a840f94c359 100644 --- a/xml/System.IO.Log/IRecordSequence.xml +++ b/xml/System.IO.Log/IRecordSequence.xml @@ -25,15 +25,15 @@ The interface provides the following capabilities, -- Append log records using the methods. +- Append log records using the methods. -- Read the appended records using the method. +- Read the appended records using the method. -- Write a special restart record using the method. +- Write a special restart record using the method. -- Read restart records from the most recently written restart record using the method. +- Read restart records from the most recently written restart record using the method. -- Flush the records to durable store using the method. +- Flush the records to durable store using the method. - Reserve space for appending records. @@ -55,7 +55,7 @@ - The property contains the total size of all reservations made in this record sequence. -- If the property is set to `true`, and an operation fails because there is no space in the sequence, the record sequence will attempt to free space, and retry the Append operation. +- If the property is set to `true`, and an operation fails because there is no space in the sequence, the record sequence will attempt to free space, and retry the Append operation. ]]> @@ -144,7 +144,7 @@ ## Remarks Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -189,7 +189,7 @@ ## Remarks Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -238,7 +238,7 @@ The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -287,7 +287,7 @@ The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -320,9 +320,9 @@ and less than . + Valid sequence numbers are greater than or equal to and less than . - The value of this property can be changed by calling the or method. + The value of this property can be changed by calling the or method. ]]> @@ -375,11 +375,11 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -426,11 +426,11 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -479,13 +479,13 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -534,13 +534,13 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -581,11 +581,11 @@ returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. Calling this method ensures that all records that have been appended to the are durably written. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -644,15 +644,15 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -703,15 +703,15 @@ returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -765,7 +765,7 @@ returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method, to assure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. @@ -773,7 +773,7 @@ If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -814,7 +814,7 @@ returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. @@ -822,7 +822,7 @@ If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -883,9 +883,9 @@ is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -920,9 +920,9 @@ is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous flush request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -957,9 +957,9 @@ is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -994,9 +994,9 @@ is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -1104,10 +1104,10 @@ and less than . + This property contains a sequence number that is guaranteed to be larger than the sequence number of the last appended record. Valid sequence numbers are greater than or equal to and less than . > [!NOTE] -> When using a instance, the value can become out of date until records are flushed to the log. See and for more information on flushing records. +> When using a instance, the value can become out of date until records are flushed to the log. See and for more information on flushing records. ]]> @@ -1171,7 +1171,7 @@ ## Examples - This sample demonstrates the use of the method. + This sample demonstrates the use of the method. ```csharp using System; @@ -1290,7 +1290,7 @@ using System; The restart areas are enumerated in reverse sequence number order, that is, from the highest sequence number to the lowest sequence number. Only restart areas with sequence numbers between the last sequence number and the base sequence number are enumerated. > [!NOTE] -> If the log extent containing the becomes corrupted, this method can throw an with the error message "The request could not be performed because of an unexpected I/O exception. The following error code was returned: '80070026'". +> If the log extent containing the becomes corrupted, this method can throw an with the error message "The request could not be performed because of an unexpected I/O exception. The following error code was returned: '80070026'". ]]> @@ -1356,7 +1356,7 @@ using System; The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -1414,7 +1414,7 @@ using System; The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -1501,7 +1501,7 @@ using System; call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. + If the value of this property is `true`, and an call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. ]]> @@ -1547,7 +1547,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. ]]> @@ -1582,7 +1582,7 @@ using System; ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1621,7 +1621,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1662,7 +1662,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1705,7 +1705,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1750,7 +1750,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1758,7 +1758,7 @@ using System; When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1799,7 +1799,7 @@ using System; method. + A restart area is used to temporarily store information containing a client's last checkpoint operation. When a recovery is necessary, you can parse the restart area to retrieve all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -1807,7 +1807,7 @@ using System; When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> diff --git a/xml/System.IO.Log/LogArchiveSnapshot.xml b/xml/System.IO.Log/LogArchiveSnapshot.xml index a7908d819ad..b7f68a1a549 100644 --- a/xml/System.IO.Log/LogArchiveSnapshot.xml +++ b/xml/System.IO.Log/LogArchiveSnapshot.xml @@ -22,7 +22,7 @@ ## Remarks A object contains the information necessary to generate a consistent backup of the data in a . The actual data is contained in the enumerable collection of objects returned by the property. Each instance represents a sequence of bytes in a file that must be archived. - The , , and properties are for informational purposes only. They can be recorded along with the archive data to provide optional information, but are not required to restore the data. + The , , and properties are for informational purposes only. They can be recorded along with the archive data to provide optional information, but are not required to restore the data. diff --git a/xml/System.IO.Log/LogExtentCollection.xml b/xml/System.IO.Log/LogExtentCollection.xml index 6556ce0eb14..41f13f0ead6 100644 --- a/xml/System.IO.Log/LogExtentCollection.xml +++ b/xml/System.IO.Log/LogExtentCollection.xml @@ -29,7 +29,7 @@ ## Remarks This class contains a collection of objects associated with a . A instance stores its data in a collection of disk extents, represented by instances. A particular is associated with one , and objects in the same are of identical size. Space is added to and removed from a instance in extent increments. - Although objects are represented on disk as files, they should not be moved or deleted as normal files. Rather, you should use the methods provided by this class for adding and deleting instances directly. Extents are usually removed when they no longer contain any active data. However, if the `force` parameter in the method is `true`, an exception is thrown if they cannot be removed immediately. + Although objects are represented on disk as files, they should not be moved or deleted as normal files. Rather, you should use the methods provided by this class for adding and deleting instances directly. Extents are usually removed when they no longer contain any active data. However, if the `force` parameter in the method is `true`, an exception is thrown if they cannot be removed immediately. You cannot remove the last extent in the , which means that the property cannot be zero after an extent is added. diff --git a/xml/System.IO.Log/LogPolicy.xml b/xml/System.IO.Log/LogPolicy.xml index 7607cecd2c7..e0e22ae018e 100644 --- a/xml/System.IO.Log/LogPolicy.xml +++ b/xml/System.IO.Log/LogPolicy.xml @@ -22,7 +22,7 @@ ## Remarks A policy is a set of rules to be followed by a instance and its clients. A instance is used to examine and modify the policy associated with a specific . A policy can describe the minimum and maximum allowable log sizes, or how the instance is allowed to grow. In addition, you can also control whether a instance can be archived. - After changing any of the properties, you should use the method to ensure that the changes are applied to the . You can call the method to discard changes or to get the most current policy. + After changing any of the properties, you should use the method to ensure that the changes are applied to the . You can call the method to discard changes or to get the most current policy. @@ -129,7 +129,7 @@ after making any changes to ensure that the changes are recorded. + You must call after making any changes to ensure that the changes are recorded. @@ -178,7 +178,7 @@ becomes full, this policy value determines how much more space can be added. Space will not be added if it causes the number of extents in the to exceed . + When the becomes full, this policy value determines how much more space can be added. Space will not be added if it causes the number of extents in the to exceed . diff --git a/xml/System.IO.Log/LogRecord.xml b/xml/System.IO.Log/LogRecord.xml index b8308a2b5c8..da3ee1cd7c8 100644 --- a/xml/System.IO.Log/LogRecord.xml +++ b/xml/System.IO.Log/LogRecord.xml @@ -87,14 +87,14 @@ Releases all resources used by the . - instance. The method leaves the instance in an unusable state. After calling this method, you must release all references to the instance, so that the garbage collector can reclaim the memory that the instance was occupying. - + instance. The method leaves the instance in an unusable state. After calling this method, you must release all references to the instance, so that the garbage collector can reclaim the memory that the instance was occupying. + > [!NOTE] -> Always call before you release your last reference to the instance. Otherwise, the resources it is using cannot be freed until the garbage collector calls the instance's `Finalize` method. - +> Always call before you release your last reference to the instance. Otherwise, the resources it is using cannot be freed until the garbage collector calls the instance's `Finalize` method. + ]]> @@ -119,11 +119,11 @@ When overridden in a derived class, gets the sequence number of the previous record. The sequence number of the previous record. - method. Aside from its use in enumeration, this sequence number is treated as opaque by the record sequence. - + method. Aside from its use in enumeration, this sequence number is treated as opaque by the record sequence. + ]]> @@ -170,11 +170,11 @@ When overridden in a derived class, gets the sequence number of the next record. The sequence number of the next record in the user-specified chain. - method. Aside from its use in enumeration, this sequence number is treated as opaque by the record sequence. - + method. Aside from its use in enumeration, this sequence number is treated as opaque by the record sequence. + ]]> diff --git a/xml/System.IO.Log/LogRecordEnumeratorType.xml b/xml/System.IO.Log/LogRecordEnumeratorType.xml index 139a779e421..00ea6247c0e 100644 --- a/xml/System.IO.Log/LogRecordEnumeratorType.xml +++ b/xml/System.IO.Log/LogRecordEnumeratorType.xml @@ -16,11 +16,11 @@ Specifies the manner in which records should be read from a . - method to control the order in which records should be read. Each value corresponds to one of the metadata sequence numbers stored in a log record. - + method to control the order in which records should be read. Each value corresponds to one of the metadata sequence numbers stored in a log record. + ]]> diff --git a/xml/System.IO.Log/LogRecordSequence.xml b/xml/System.IO.Log/LogRecordSequence.xml index 86d065d05cb..c0469a44288 100644 --- a/xml/System.IO.Log/LogRecordSequence.xml +++ b/xml/System.IO.Log/LogRecordSequence.xml @@ -455,14 +455,14 @@ event to free up space in a record. The event indicates that the tail of the sequence (that is, the base sequence number) needs to be moved forward to free up space. Freeing space can be done by either writing restart areas using the method, or truncating the log and using the method to advance the base sequence number of a log to the one specified by the `newBaseSequenceNumber` parameter. The code sample in the Example section demonstrates the second approach. + This method is often used with the event to free up space in a record. The event indicates that the tail of the sequence (that is, the base sequence number) needs to be moved forward to free up space. Freeing space can be done by either writing restart areas using the method, or truncating the log and using the method to advance the base sequence number of a log to the one specified by the `newBaseSequenceNumber` parameter. The code sample in the Example section demonstrates the second approach. - Note that calling this method is the same as setting a new base sequence number using the method, except that no restart record is written to the log. + Note that calling this method is the same as setting a new base sequence number using the method, except that no restart record is written to the log. ## Examples - This example shows how to use the method with the event to free up space in a log sequence. + This example shows how to use the method with the event to free up space in a log sequence. ``` recordSequence.RetryAppend = true; @@ -516,7 +516,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) member + This example shows how to use the member :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet5"::: @@ -563,7 +563,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. @@ -638,7 +638,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -709,7 +709,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -781,7 +781,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -837,14 +837,14 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) and less than . + Valid sequence numbers are greater than or equal to and less than . - The value of this property can be changed by calling the method or method. + The value of this property can be changed by calling the method or method. ## Examples - This example shows how to use the member in a loop. + This example shows how to use the member in a loop. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: @@ -903,11 +903,11 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -976,11 +976,11 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -1051,13 +1051,13 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -1129,13 +1129,13 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -1199,11 +1199,11 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. Calling this method ensures that all records that have been appended to the are durably written. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1273,15 +1273,15 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1355,15 +1355,15 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1420,7 +1420,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. @@ -1428,7 +1428,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1501,7 +1501,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + You should pass the returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. @@ -1509,7 +1509,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -1636,7 +1636,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. to release resources: + This example shows how to use to release resources: :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: @@ -1680,9 +1680,9 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -1732,9 +1732,9 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous flush request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -1780,9 +1780,9 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -1832,9 +1832,9 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. is called. + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, become visible when is called. - This method must be called exactly once on every returned by the method. + This method must be called exactly once on every returned by the method. ]]> @@ -1972,7 +1972,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. and less than . All other sequence numbers are invalid. + This property contains a sequence number that is guaranteed to be larger than the sequence number of the last appended record. Valid sequence numbers are greater than or equal to and less than . All other sequence numbers are invalid. ]]> @@ -2002,7 +2002,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. member to add extents. + This example shows how to use the member to add extents. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: @@ -2073,7 +2073,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. ## Examples - This example shows how to use in a loop. + This example shows how to use in a loop. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: @@ -2243,7 +2243,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. @@ -2345,7 +2345,7 @@ recordSequence.Append(undoRecordData, // If necessary … The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. ]]> @@ -2416,7 +2416,7 @@ recordSequence.Append(undoRecordData, // If necessary … ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - Using the method, you can remove the most recently written restart area. + Using the method, you can remove the most recently written restart area. ]]> @@ -2450,7 +2450,7 @@ recordSequence.Append(undoRecordData, // If necessary … call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. + If the value of this property is `true`, and an call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. @@ -2547,9 +2547,9 @@ recordSequence.Append(undoRecordData, // If necessary … ## Remarks You can fire this event when the record sequence has run out of space. When this event is fired, the tail of the sequence (that is, the base sequence number) is moved forward to free up space. - The event can be fired at any time when the record sequence decides that it must free up space, for any reason. For example, the CLFS policy engine may decide to fire the event when it determines that the tails of two log clients sharing the same log file are too far apart. Freeing space can be done by either writing restart areas, or truncating the log and using the method to clear space. The code sample in the Example section demonstrates the second approach. + The event can be fired at any time when the record sequence decides that it must free up space, for any reason. For example, the CLFS policy engine may decide to fire the event when it determines that the tails of two log clients sharing the same log file are too far apart. Freeing space can be done by either writing restart areas, or truncating the log and using the method to clear space. The code sample in the Example section demonstrates the second approach. - You can also call the method outside of the event to free space. A restart area is similar to a checkpoint in other log processing systems. Calling this method indicates that the application considers all prior records before the restart area as fully completed, and usable for future record appends. Similar to any other records, the record written by this method requires actual free space in the log to function. + You can also call the method outside of the event to free space. A restart area is similar to a checkpoint in other log processing systems. Calling this method indicates that the application considers all prior records before the restart area as fully completed, and usable for future record appends. Similar to any other records, the record written by this method requires actual free space in the log to function. @@ -2593,7 +2593,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. ]]> @@ -2631,7 +2631,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -2678,7 +2678,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -2727,13 +2727,13 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -2777,13 +2777,13 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -2829,7 +2829,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -2837,7 +2837,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> @@ -2883,7 +2883,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) ## Remarks A restart area is used to temporarily store information containing a client's last checkpoint operation. The Common Log File System (CLFS) maintains two restart areas to guarantee that at least one valid area is always available. When a recovery is necessary, the CLFS reads its restart area and all the data from the last checkpoint operation. This data initializes the transaction table, dirty pages table, and open file table so they can be used in the recovery process. - A restart area can be read using the method. + A restart area can be read using the method. When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. @@ -2891,7 +2891,7 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. ]]> diff --git a/xml/System.IO.Log/LogStore.xml b/xml/System.IO.Log/LogStore.xml index 19ba243a69d..2ccd9539246 100644 --- a/xml/System.IO.Log/LogStore.xml +++ b/xml/System.IO.Log/LogStore.xml @@ -28,7 +28,7 @@ The relationship between the class and the class is similar to the relationship between a disk file and a object. The disk file provides the actual storage and has attributes such as length and last access time, while the object provides a view on the file that can be used to read from it and write to it. Similarly, the class has attributes like a policy and a collection of disk extents, and the class provides a record-oriented mechanism for reading and writing data. - Unlike the file record sequence represented by the class, a instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which can be returned by the property. + Unlike the file record sequence represented by the class, a instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which can be returned by the property. A instance can have policies associated with it. These are represented by instances that can be returned by the property. A policy dictates rules that the log will attempt to follow, such as maximum number of extents and minimum size, and instructions on growing or shrinking the under certain conditions. In addition, you can specify whether a instance can be archived. Policies are set per log and are volatile, which means that once every handle to the log is closed, the policy no longer exists. @@ -386,7 +386,7 @@ is not archivable, calls to the and methods result in a being thrown. + If a is not archivable, calls to the and methods result in a being thrown. ]]> @@ -416,7 +416,7 @@ and less than . + Valid sequence numbers are greater than or equal to and less than . ]]> @@ -585,10 +585,10 @@ when you have finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you have finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> @@ -618,7 +618,7 @@ instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which is returned by this property. + A instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which is returned by this property. ]]> @@ -692,7 +692,7 @@ and less than . + Valid sequence numbers are greater than or equal to and less than . ]]> diff --git a/xml/System.IO.Log/PolicyUnit.xml b/xml/System.IO.Log/PolicyUnit.xml index 68461298ad6..0fc1b9bda45 100644 --- a/xml/System.IO.Log/PolicyUnit.xml +++ b/xml/System.IO.Log/PolicyUnit.xml @@ -22,7 +22,7 @@ ## Remarks The structure represents a size measurement in a log store policy. The enumeration lists the units of measurement that can be represented. - You can use the property to determine the size of the measurement. To determine the unit of measurement, use the property. You can convert other data types to a by using the and methods. + You can use the property to determine the size of the measurement. To determine the unit of measurement, use the property. You can convert other data types to a by using the and methods. @@ -184,7 +184,7 @@ instances for equality. For both objects to be equal, they must have the same values for both the and properties. + Use this operator to compare two instances for equality. For both objects to be equal, they must have the same values for both the and properties. ]]> @@ -220,7 +220,7 @@ instances for inequality. For both objects to not be equal, they must have different values for the and properties. + Use this operator to compare two instances for inequality. For both objects to not be equal, they must have different values for the and properties. ]]> diff --git a/xml/System.IO.Log/RecordAppendOptions.xml b/xml/System.IO.Log/RecordAppendOptions.xml index 3c416263acc..a05cbf636bc 100644 --- a/xml/System.IO.Log/RecordAppendOptions.xml +++ b/xml/System.IO.Log/RecordAppendOptions.xml @@ -22,14 +22,14 @@ Specifies how records are appended. - method to append a record to a log sequence. - + method to append a record to a log sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.IO.Log/ReservationCollection.xml b/xml/System.IO.Log/ReservationCollection.xml index fbb212fd9f6..0c16c444cd3 100644 --- a/xml/System.IO.Log/ReservationCollection.xml +++ b/xml/System.IO.Log/ReservationCollection.xml @@ -39,16 +39,16 @@ Reservations can be used to guarantee that an operation can be completed before the data is committed; otherwise, the changes are rolled back. It can also be used to record an "undo action" in the log. During a rollback operation, a transactional resource manager (RM) must be able to recover its state if the RM is interrupted during the rollback operation. By using a reservation area, an RM can reserve space in a log before it is used. - The method can either reserve space or append data, or both, depending on the parameters that are specified when making the call. As work progresses in a transaction, an application can append the undo information and reserve space for compensation records. During a rollback operation, compensation records that are created indicate what has been undone on the disk. The records are appended using space that has been previously reserved. This guarantees that an RM does not run out of log space, which is a fatal condition, while performing a rollback operation. If a log fills up during a transaction, an application can safely roll back a transaction without corrupting durable data. + The method can either reserve space or append data, or both, depending on the parameters that are specified when making the call. As work progresses in a transaction, an application can append the undo information and reserve space for compensation records. During a rollback operation, compensation records that are created indicate what has been undone on the disk. The records are appended using space that has been previously reserved. This guarantees that an RM does not run out of log space, which is a fatal condition, while performing a rollback operation. If a log fills up during a transaction, an application can safely roll back a transaction without corrupting durable data. CLFS is an ARIES-compliant logging system, meant for write-ahead logging. In write-ahead logging, an application writes an undo record before it performs the operation, reserving the amount of space it takes in the log to write a compensating record, which may be used during rollback. Later, the reserved space is used when the compensation record is actually written. - Applications can either reserve or access long space at any given time (they are mutually exclusive operations). After a commit record is written to the log, an application can free up the reservations for the compensation records. This action can be done by calling either the or method. Calling the method guarantees that the operation is atomic, while calling the method does not. + Applications can either reserve or access long space at any given time (they are mutually exclusive operations). After a commit record is written to the log, an application can free up the reservations for the compensation records. This action can be done by calling either the or method. Calling the method guarantees that the operation is atomic, while calling the method does not. - When you free records, you must free the same records that you reserved together in a previous call to the method. + When you free records, you must free the same records that you reserved together in a previous call to the method. > [!NOTE] -> Your implementation of must implement the and methods to perform the actual reservation allocation and deallocation. In addition, your implementation must also call when a record is written into a reserved space. +> Your implementation of must implement the and methods to perform the actual reservation allocation and deallocation. In addition, your implementation must also call when a record is written into a reserved space. @@ -376,7 +376,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. method should be called to ensure that the accurately represents the amount of reserved space in the record sequence. + This method is typically called when appending a record from reserved space to a record sequence. When it returns, a reservation of the returned size has been removed from the collection. If, for some reason, the reserved space is not actually accessed, the method should be called to ensure that the accurately represents the amount of reserved space in the record sequence. ]]> @@ -595,7 +595,7 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. , you must call this method when a reservation is made outside of a call to . + When you inherit from , you must call this method when a reservation is made outside of a call to . ]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml index 54a851e3176..05a320c8700 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml @@ -60,9 +60,9 @@ ## Remarks A memory-mapped file maps the contents of a file to an application's logical address space. Memory-mapped files enable programmers to work with extremely large files because memory can be managed concurrently, and they allow complete, random access to a file without the need for seeking. Memory-mapped files can also be shared across multiple processes. - The methods create a memory-mapped file from a specified path or a of an existing file on disk. Changes are automatically propagated to disk when the file is unmapped. + The methods create a memory-mapped file from a specified path or a of an existing file on disk. Changes are automatically propagated to disk when the file is unmapped. - The methods create a memory-mapped file that is not mapped to an existing file on disk; and are suitable for creating shared memory for interprocess communication (IPC). + The methods create a memory-mapped file that is not mapped to an existing file on disk; and are suitable for creating shared memory for interprocess communication (IPC). A memory-mapped file can be associated with an optional name that allows the memory-mapped file to be shared with other processes. @@ -137,7 +137,7 @@ method to create a memory-mapped file, and then creates a memory-mapped view to a portion of an extremely large file. + The following example uses the method to create a memory-mapped file, and then creates a memory-mapped view to a portion of an extremely large file. :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.MemoryMappedFiles/MemoryMappedFile/Overview/program.vb" id="Snippet1"::: @@ -1797,7 +1797,7 @@ Process C says: True ## Examples - The following example creates a stream and writes a value to it. This code example is part of a larger example provided for the method. + The following example creates a stream and writes a value to it. This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/CreateNew/program2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.MemoryMappedFiles/MemoryMappedFile/CreateNew/program2.vb" id="Snippet2"::: @@ -2194,14 +2194,14 @@ Process C says: True ## Examples **Opening a Persisted Memory-Mapped File** - The following example opens a memory-mapped file named `ImgA` that has already been created from a file on disk (as shown in the example for the method). + The following example opens a memory-mapped file named `ImgA` that has already been created from a file on disk (as shown in the example for the method). :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/OpenExisting/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.MemoryMappedFiles/MemoryMappedFile/OpenExisting/program.vb" id="Snippet1"::: **Opening a Non-Persisted Memory-Mapped File** - The following example opens a memory-mapped file used for inter-process communication. This code example is part of a larger example provided for the method. + The following example opens a memory-mapped file used for inter-process communication. This code example is part of a larger example provided for the method. ]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml index 5d0642b2f39..4c3ea97e417 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml @@ -50,11 +50,11 @@ Specifies access rights to a memory-mapped file that is not associated with a file on disk. - method to open an existing memory-mapped file. - + method to open an existing memory-mapped file. + ]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileSecurity.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileSecurity.xml index c66c9d9259b..7362f2a3989 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileSecurity.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileSecurity.xml @@ -20,27 +20,27 @@ Represents the permissions that can be granted for file access and operations on memory-mapped files. - class specifies the access rights for a memory-mapped file and how access attempts are audited. This class represents access and audit rights as a set of rules. - - The class is an abstraction of the underlying Microsoft Windows file security system. In this system. It hides many of the details of DACLs and SACLs. - - Use the class to retrieve, add, or change the access rules that represent the DACL and SACL of a pipe. - - To apply new or changed access or audit rules to a memory-mapped file, use the method. To retrieve access or audit rules from an existing file, use the method. - - The following methods take a object as a parameter: - -- - -- - -- - -- - + class specifies the access rights for a memory-mapped file and how access attempts are audited. This class represents access and audit rights as a set of rules. + + The class is an abstraction of the underlying Microsoft Windows file security system. In this system. It hides many of the details of DACLs and SACLs. + + Use the class to retrieve, add, or change the access rules that represent the DACL and SACL of a pipe. + + To apply new or changed access or audit rules to a memory-mapped file, use the method. To retrieve access or audit rules from an existing file, use the method. + + The following methods take a object as a parameter: + +- + +- + +- + +- + ]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewAccessor.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewAccessor.xml index 60ce1c78a5a..c2f98bfdacc 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewAccessor.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewAccessor.xml @@ -54,7 +54,7 @@ method of a object to get this view. + Use the method of a object to get this view. diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml index 8fa20d102c7..d5c13cc2836 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml @@ -54,14 +54,14 @@ method of a object to get this stream. + Use the method of a object to get this stream. ## Examples The following example obtains a of a memory-mapped file and writes a value to the stream for inter-process communication. - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/CreateNew/program2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.MemoryMappedFiles/MemoryMappedFile/CreateNew/program2.vb" id="Snippet2"::: diff --git a/xml/System.IO.Packaging/CertificateEmbeddingOption.xml b/xml/System.IO.Packaging/CertificateEmbeddingOption.xml index aae9cfa592c..651e9a5b5db 100644 --- a/xml/System.IO.Packaging/CertificateEmbeddingOption.xml +++ b/xml/System.IO.Packaging/CertificateEmbeddingOption.xml @@ -29,7 +29,7 @@ If the certificate is `NotEmbedded` in the package, an application that verifies signatures must provide a copy of the certificate in order to verify the signatures that are signed by it. -`InSignaturePart` adds two informational elements, `` and ``, as part of the field of the stored digital signature. The `` and `` elements are not processed as part of signature validation and are therefore not secure from modification. Applications should not make any assumption regarding the validity of these two elements. To avoid undetected modification and possible confusion, applications should use the `InCertificatePart` option instead of `InSignaturePart`. The `InCertificatePart` option does not provide or expose either `` or ``. +`InSignaturePart` adds two informational elements, `` and ``, as part of the field of the stored digital signature. The `` and `` elements are not processed as part of signature validation and are therefore not secure from modification. Applications should not make any assumption regarding the validity of these two elements. To avoid undetected modification and possible confusion, applications should use the `InCertificatePart` option instead of `InSignaturePart`. The `InCertificatePart` option does not provide or expose either `` or ``. ## Examples diff --git a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml index f9452aafca4..beef328828c 100644 --- a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml +++ b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml @@ -31,7 +31,7 @@ has no public constructors. An is created by use of the static , , or methods. + has no public constructors. An is created by use of the static , , or methods. ]]> @@ -202,7 +202,7 @@ method to instantiate an . + The following example shows how to use the method to instantiate an . :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: @@ -257,7 +257,7 @@ ## Examples - The following example shows how to use the method to instantiate an . + The following example shows how to use the method to instantiate an . :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: @@ -318,7 +318,7 @@ ## Examples - The following example shows how to use the method to instantiate an . + The following example shows how to use the method to instantiate an . :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: @@ -372,10 +372,10 @@ when finished with a . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when finished with a . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> diff --git a/xml/System.IO.Packaging/PackUriHelper.xml b/xml/System.IO.Packaging/PackUriHelper.xml index 9397db074aa..0771426f4d6 100644 --- a/xml/System.IO.Packaging/PackUriHelper.xml +++ b/xml/System.IO.Packaging/PackUriHelper.xml @@ -112,7 +112,7 @@ returns 0. When comparing pack URIs, a null URI is always less than a non-null URI. For cases where `firstPackUri` and `secondPackUri` are both absolute pack URIs, performs the comparison. + If both `firstPackUri` and `secondPackUri` are `null`, returns 0. When comparing pack URIs, a null URI is always less than a non-null URI. For cases where `firstPackUri` and `secondPackUri` are both absolute pack URIs, performs the comparison. ]]> @@ -185,7 +185,7 @@ returns 0. When comparing URIs, a null URI is always less than a non-null URI. For cases where `firstPartUri` and `secondPartUri` are both relative URIs, performs the comparison. + If both `firstPartUri` and `secondPartUri` are `null`, returns 0. When comparing URIs, a null URI is always less than a non-null URI. For cases where `firstPartUri` and `secondPartUri` are both relative URIs, performs the comparison. ]]> @@ -205,7 +205,7 @@ method. + The following table illustrates sample cases for the method. |`packageUri`|`partUri`|`fragment`|Returned pack URI| |------------------|---------------|----------------|-----------------------| @@ -276,7 +276,7 @@ ## Remarks `packageUri` may not be specified as `null` or empty. - The following table illustrates sample cases for . + The following table illustrates sample cases for . |`packageUri`|Returned pack URI| |------------------|-----------------------| @@ -291,7 +291,7 @@ ## Examples - The following example shows how to use the method to define a pack URI that references a package. + The following example shows how to use the method to define a pack URI that references a package. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubgetfixdoc"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubgetfixdoc"::: @@ -364,7 +364,7 @@ If `partUri` is `null`, the returned pack URI points to the package. - The following table illustrates sample cases for the method. + The following table illustrates sample cases for the method. |`packageUri`|`partUri`|Returned pack URI| |------------------|---------------|-----------------------| @@ -383,7 +383,7 @@ ## Examples - The following example shows how to use the method to define a pack URI that references a package. + The following example shows how to use the method to define a pack URI that references a package. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubgetfixdoc"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubgetfixdoc"::: @@ -465,7 +465,7 @@ `fragment` cannot be an empty string but can be specified as `null`. When not specified as `null`, the `fragment` string must begin with a '#' character. For more information of the syntax of `fragment` references, see Section 3.5 "Fragment" of [RFC 3986](https://www.ietf.org/rfc/rfc3986.txt). - The following table illustrates sample cases for the method. + The following table illustrates sample cases for the method. |`packageUri`|`partUri`|`fragment`|Returned pack URI| |------------------|---------------|----------------|-----------------------| @@ -487,7 +487,7 @@ ## Examples - The following example shows how to use the method to define a pack URI that references a package. + The following example shows how to use the method to define a pack URI that references a package. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubgetfixdoc"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubgetfixdoc"::: @@ -553,7 +553,7 @@ The returned URI is an absolute path that always starts with "/" and conforms to the syntax defined in the [Open Packaging Conventions Specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/). - The following table illustrates sample cases for . + The following table illustrates sample cases for . | `partUri` | Returned Part URI | |---------------|-------------------| @@ -563,7 +563,7 @@ | /b/bar.xaml | /b/bar.xaml | ## Examples - The following example shows how to use the method to define relative URIs for elements. + The following example shows how to use the method to define relative URIs for elements. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/Package/Overview/PackageWrite.cs" id="Snippetpackagewritecreateparturi"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageWrite/visualbasic/packagewrite.vb" id="Snippetpackagewritecreateparturi"::: @@ -619,7 +619,7 @@ normalizes `partUri` by case-folding to uppercase () and returning the result. + normalizes `partUri` by case-folding to uppercase () and returning the result. ]]> @@ -674,7 +674,7 @@ . + The following table illustrates sample cases for . |`packUri`|Returned Package URI| |---------------|--------------------------| @@ -743,7 +743,7 @@ ## Remarks The returned URI is relative to the package root and is an absolute path that always starts with "/" and conforms to the syntax defined in the [Open Packaging Conventions Specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/). - The following table illustrates sample cases for . + The following table illustrates sample cases for . |`packUri`|Returned Part URI| |---------------|-----------------------| @@ -880,7 +880,7 @@ The partUri extracted from does not conform to the v . + The following table illustrates sample cases for . |`sourcePartUri`|`targetPartUri`|Returned relative URI| |---------------------|---------------------|---------------------------| @@ -937,9 +937,9 @@ The partUri extracted from does not conform to the v property of a relationship part must identify either the ("/") or a that is not a . + The property of a relationship part must identify either the ("/") or a that is not a . - For example, if the package part "/files/document.xaml" is the source owner of the relationship part "/files/_rels/document.xaml.rels", calling with the `relationshipPartUri` parameter of "/files/_rels/document.xaml.rels" returns the of "/files/document.xaml". + For example, if the package part "/files/document.xaml" is the source owner of the relationship part "/files/_rels/document.xaml.rels", calling with the `relationshipPartUri` parameter of "/files/_rels/document.xaml.rels" returns the of "/files/document.xaml". ]]> @@ -1062,7 +1062,7 @@ This method does not inspect the part contents; it is based solely on the name. . + The following table illustrates sample cases for . |`sourcePartUri`|`targetUri`|Returned URI| |---------------------|-----------------|------------------| @@ -1074,7 +1074,7 @@ This method does not inspect the part contents; it is based solely on the name. |/|images/picture.jpg|/images/picture.jpg| ## Examples - The following example shows how to use the method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/Package/GetPart/PackageRead.cs" id="Snippetpackagereadusing"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageRead/visualbasic/packageread.vb" id="Snippetpackagereadusing"::: diff --git a/xml/System.IO.Packaging/PackWebRequest.xml b/xml/System.IO.Packaging/PackWebRequest.xml index f00b50889f5..137d65fc027 100644 --- a/xml/System.IO.Packaging/PackWebRequest.xml +++ b/xml/System.IO.Packaging/PackWebRequest.xml @@ -72,7 +72,7 @@ property is distinct from the of the inner returned by the method. + The property is distinct from the of the inner returned by the method. ]]> @@ -113,7 +113,7 @@ The property is an empty string if the request resolves from the cache. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -151,9 +151,9 @@ ## Remarks Note that the pack URI protocol does not process information in the request other than the uniform resource identifier (URI). For most traditional purposes (such as estimating the size of POST information), there is no need for this property. - returns 0 if the request resolves from the cache. + returns 0 if the request resolves from the cache. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -192,9 +192,9 @@ ## Remarks Note that the pack URI protocol does not process information in the request other than the uniform resource identifier (URI). For most purposes (such as determining the type of POST information), there is no use for this property. - returns an empty string if the request resolves from the cache. + returns an empty string if the request resolves from the cache. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -232,7 +232,7 @@ ## Remarks Requests to the package cache use their own cached credentials. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -270,7 +270,7 @@ is provided for advanced scenarios only and is not needed for normal operation. + The is provided for advanced scenarios only and is not needed for normal operation. ]]> @@ -308,7 +308,7 @@ exists to implement the contract required by the abstract base class. The pack URI protocol does not support writing. + exists to implement the contract required by the abstract base class. The pack URI protocol does not support writing. ]]> @@ -353,9 +353,9 @@ returns value of type . The return value it is actually of type specific to the response of the pack URI protocol. + Per the signature of the base class, returns value of type . The return value it is actually of type specific to the response of the pack URI protocol. - The method should be called when the application is finished with the stream. + The method should be called when the application is finished with the stream. ]]> @@ -393,7 +393,7 @@ ## Remarks Package cache requests include a valid but otherwise empty header collection in their requests. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -431,7 +431,7 @@ ## Remarks The property returns an empty string if the request resolves from the cache. The property is only set when request references an external Web request, such as http or ftp. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -470,7 +470,7 @@ ## Remarks The property returns `false` for requests resolved from the cache; there is no pre-authentication scheme for the pack URI protocol. - The property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -516,7 +516,7 @@ property is shared with the inner (). + The property is shared with the inner (). ]]> @@ -588,9 +588,9 @@ cache, returns a value of -1. + Requests to the package cache do not time out. For requests that resolve from the cache, returns a value of -1. - The property is shared with the inner request (). + The property is shared with the inner request (). ]]> diff --git a/xml/System.IO.Packaging/PackWebResponse.xml b/xml/System.IO.Packaging/PackWebResponse.xml index 95a17480605..d98c2a46554 100644 --- a/xml/System.IO.Packaging/PackWebResponse.xml +++ b/xml/System.IO.Packaging/PackWebResponse.xml @@ -151,11 +151,11 @@ Requests that specify a part in the package return one of the following: -1. If the requested part contains a value, the value is returned. +1. If the requested part contains a value, the value is returned. -2. If the requested part contains no value but the stream name contains a recognized MIME extension type, the MIME type corresponding to the extension is returned. +2. If the requested part contains no value but the stream name contains a recognized MIME extension type, the MIME type corresponding to the extension is returned. -3. If the requested part does not contain a value nor a recognized MIME extension type, returns an empty string. +3. If the requested part does not contain a value nor a recognized MIME extension type, returns an empty string. ]]> @@ -291,7 +291,7 @@ returns `null` when the response is from the package cache (when is `true`). + returns `null` when the response is from the package cache (when is `true`). ]]> diff --git a/xml/System.IO.Packaging/Package.xml b/xml/System.IO.Packaging/Package.xml index 446c2c8cb85..fa4ba53d976 100644 --- a/xml/System.IO.Packaging/Package.xml +++ b/xml/System.IO.Packaging/Package.xml @@ -62,18 +62,18 @@ Like a file system, items contained in a are referenced in a hierarchical organization of folders and files. - Although itself is an abstract class, the derived class is used as default by the method. + Although itself is an abstract class, the derived class is used as default by the method. A ("part") is the abstract class that represents an object that is stored in a . A ("relationship") defines an association between a source or and a target object. A can be one of two types, each of which can be one of two forms: -- A package-level relationship (created by the method) relates a to either: +- A package-level relationship (created by the method) relates a to either: - A target part in the package. - A target resource outside the package. -- A part-level relationship (created by the method) relates a source to either: +- A part-level relationship (created by the method) relates a source to either: - Another target part in the package. - A target resource outside the package. @@ -154,7 +154,7 @@ is a protected constructor of the abstract base class. When called in a derived class, the constructor initializes a new instance of the derived class. + is a protected constructor of the abstract base class. When called in a derived class, the constructor initializes a new instance of the derived class. ]]> @@ -191,7 +191,7 @@ is a protected constructor of the abstract base abstract base class. When called in a derived class, the constructor initializes a new instance of the derived class. + is a protected constructor of the abstract base abstract base class. When called in a derived class, the constructor initializes a new instance of the derived class. ]]> @@ -235,12 +235,12 @@ class and perform the same operation - there is no reason to call if you call , or vice-versa. + For the class and perform the same operation - there is no reason to call if you call , or vice-versa. - and internally call . + and internally call . > [!NOTE] -> The `using` statement (different from the `using` namespace directive) is the recommended way to and a package. +> The `using` statement (different from the `using` namespace directive) is the recommended way to and a package. ]]> @@ -259,7 +259,7 @@ initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. For more information about package parts, see section 1.1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -325,9 +325,9 @@ initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. - The part is . + The part is . For additional information about package parts, see section 1.1 in the Open Packaging Conventions (OPC) specification available for download at . @@ -401,9 +401,9 @@ derived class, the method only supports two `compressionOption` values, or compression. Other values of , , or use compression. + For the default derived class, the method only supports two `compressionOption` values, or compression. Other values of , , or use compression. - creates an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + creates an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -478,11 +478,11 @@ method is called by the method to create a part based on the physical format implemented in the derived class. + The derived method is called by the method to create a part based on the physical format implemented in the derived class. - By default, a derived class implementation of the abstract class is provided and used. In the default operation, internally calls of the class to create a new part in a ZIP file. + By default, a derived class implementation of the abstract class is provided and used. In the default operation, internally calls of the class to create a new part in a ZIP file. - For the default derived class, the method only supports two `compressionOption` values, or compression. Other values of , , or use compression. + For the default derived class, the method only supports two `compressionOption` values, or compression. Other values of , , or use compression. For more information about the package model and package parts, see Chapter 1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -581,7 +581,7 @@ In a package-relationship the package is considered the "owner" of the relationship. When the package is deleted, all the relationships owned by the package are also deleted. - does not physically change the target part or resource in any way. + does not physically change the target part or resource in any way. The target of a relationship cannot be another relationship. @@ -602,7 +602,7 @@ For more information about packaging and package relationships, see section 1.3 of the Open Packaging Conventions (OPC) specification available for download at . ## Examples - The following example illustrates how to use to create a between a and a root document part. + The following example illustrates how to use to create a between a and a root document part. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/Package/Overview/PackageWrite.cs" id="Snippetpackagewritecreatepackagerelationship"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageWrite/visualbasic/packagewrite.vb" id="Snippetpackagewritecreatepackagerelationship"::: @@ -683,7 +683,7 @@ In a package-relationship the package is considered the "owner" of the relationship. When the package is deleted, all the relationships owned by the package are also deleted. - does not physically change the target part or resource in any way. + does not physically change the target part or resource in any way. The target of a relationship cannot be another relationship. @@ -708,7 +708,7 @@ For additional information about packaging and package relationships, see section 1.3 of the Open Packaging Conventions (OPC) specification available for download at . ## Examples - The following example illustrates how to use to create a between a and a root document part. + The following example illustrates how to use to create a between a and a root document part. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/Package/Overview/PackageWrite.cs" id="Snippetpackagewritecreatepackagerelationship"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageWrite/visualbasic/packagewrite.vb" id="Snippetpackagewritecreatepackagerelationship"::: @@ -772,7 +772,7 @@ ## Remarks `partUri` must be a relative URI that consists of an absolute path which starts with a forward slash ("/") character. The absolute path is relative to the package root and is formed according to the [RFC 3986](https://tools.ietf.org/html/rfc3986) Uniform Resource Identifier (URI) Generic Syntax specification. "/page1.xaml" and "/images/picture4.jpg" are examples of valid part URIs. - No exception is raised if a part with the specified `partUri` is not in the package. (You can use the method to determine whether a part with a specified `partUri` is in the package.) + No exception is raised if a part with the specified `partUri` is not in the package. (You can use the method to determine whether a part with a specified `partUri` is in the package.) For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -833,7 +833,7 @@ derived class implementation of the abstract class is provided and used. In the default operation, internally calls of the class to perform the actual delete operation based on the physical format implemented in the derived class. + By default, a derived class implementation of the abstract class is provided and used. In the default operation, internally calls of the class to perform the actual delete operation based on the physical format implemented in the derived class. For more information about the package model and package parts, see Chapter 1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -895,7 +895,7 @@ No exception is raised if a relationship with the specified `id` is not in the package. - does not physically change the target part in any way. + does not physically change the target part in any way. For more information about package relationships, see section 1.3 of the Open Packaging Conventions (OPC) specification available for download at . @@ -949,16 +949,16 @@ also finalizes, flushes, and closes all parts and relationships that are contained in the package. + To make sure that all changes are correctly saved, also finalizes, flushes, and closes all parts and relationships that are contained in the package. - For the class, and perform the same operation - there is no reason to call if you call , or vice-versa. + For the class, and perform the same operation - there is no reason to call if you call , or vice-versa. - and internally call . + and internally call . - Derived classes that allocate and manage non-memory resources should override this method to release resources when is called. Derived-class overrides should also call and the base-class method to make sure that base-class cleanup is always performed. + Derived classes that allocate and manage non-memory resources should override this method to release resources when is called. Derived-class overrides should also call and the base-class method to make sure that base-class cleanup is always performed. > [!NOTE] -> The `using` statement (different from the `using` namespace directive) is the recommended way to and a package. +> The `using` statement (different from the `using` namespace directive) is the recommended way to and a package. ]]> @@ -1003,7 +1003,7 @@ property has no default value. The file access setting is specified in the constructor call when you create a new package, or in the call when you open an existing package. + The property has no default value. The file access setting is specified in the constructor call when you create a new package, or in the call when you open an existing package. ]]> @@ -1046,11 +1046,11 @@ internally calls the derived class's implementation to perform the actual format-specific flush operation. The derived class's method is responsible for actually saving the part and relationship content to the specific physical derived class implementation. + internally calls the derived class's implementation to perform the actual format-specific flush operation. The derived class's method is responsible for actually saving the part and relationship content to the specific physical derived class implementation. - By default, a derived implementation of the abstract base class is provided and used. In the default operation, internally calls to save the parts and relationships in a ZIP file package. + By default, a derived implementation of the abstract base class is provided and used. In the default operation, internally calls to save the parts and relationships in a ZIP file package. - is called automatically by the and methods. When or is called you do not have to call separately. + is called automatically by the and methods. When or is called you do not have to call separately. ]]> @@ -1098,7 +1098,7 @@ is called by the method to perform the actual flush operation based on the physical format implemented in the derived class. + is called by the method to perform the actual flush operation based on the physical format implemented in the derived class. ]]> @@ -1149,9 +1149,9 @@ ## Remarks An is thrown if a part with the specified `partUri` does not exist. - The method can be used to determine whether `partUri` references an existing part. + The method can be used to determine whether `partUri` references an existing part. - By default, a derived implementation of the abstract base class is provided and used. In the default operation, internally calls of the class to return a requested part from a ZIP file. + By default, a derived implementation of the abstract base class is provided and used. In the default operation, internally calls of the class to return a requested part from a ZIP file. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1228,7 +1228,7 @@ derived implementation of the abstract class is provided and used. In the default operation, internally calls of the class to retrieve a part from a ZIP file. + By default, a derived implementation of the abstract class is provided and used. In the default operation, internally calls of the class to retrieve a part from a ZIP file. For more information about the package model and package parts, see Chapter 1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -1280,11 +1280,11 @@ ## Remarks - returns a collection of all parts that are contained in the package including parts. + returns a collection of all parts that are contained in the package including parts. - will never return `null`; however, the returned collection will contain zero elements if the package contains no parts. + will never return `null`; however, the returned collection will contain zero elements if the package contains no parts. -By default, a derived implementation of the abstract base class is provided and used. In the default operation, calls the method of the class to return the parts from a ZIP file. +By default, a derived implementation of the abstract base class is provided and used. In the default operation, calls the method of the class to return the parts from a ZIP file. For more information about packages and package parts, see section 1.1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -1338,9 +1338,9 @@ For more information about packages and package parts, see section 1.1 of the Op implementation is called by the method to access and return the array of parts based on the physical format implemented in the derived class. + The derived class implementation is called by the method to access and return the array of parts based on the physical format implemented in the derived class. - By default, a derived implementation of the abstract class is provided and used. In the default operation, internally calls of the class to retrieve the parts from a ZIP file. + By default, a derived implementation of the abstract class is provided and used. In the default operation, internally calls of the class to retrieve the parts from a ZIP file. For more information about the package model and package parts, see Chapter 1 of the Open Packaging Conventions (OPC) specification available for download at . @@ -1454,7 +1454,7 @@ For more information about packages and package parts, see section 1.1 of the Op will never return `null`; however the returned collection may contain zero elements if the package contains no package-level relationships. + will never return `null`; however the returned collection may contain zero elements if the package contains no package-level relationships. A package-level relationship defines an association between the package and an associated target part or resource. A package-level relationship can be one of two forms. @@ -1515,7 +1515,7 @@ For more information about packages and package parts, see section 1.1 of the Op will never return `null`; however the returned collection may contain zero elements if there are no package-level relationships that match the specified `relationshipType`. + will never return `null`; however the returned collection may contain zero elements if there are no package-level relationships that match the specified `relationshipType`. The following table shows the package-level `relationshipType` URIs defined by the Open Packaging Conventions (OPC) specification. @@ -1560,7 +1560,7 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1614,7 +1614,7 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1665,9 +1665,9 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. - This method opens the package with default attributes , , and (to specify different attributes use one of the other Open method overloads). + This method opens the package with default attributes , , and (to specify different attributes use one of the other Open method overloads). For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1725,7 +1725,7 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1780,9 +1780,9 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. - This method opens the package with default attributes and (to specify different attributes use one of the other Open method overloads). + This method opens the package with default attributes and (to specify different attributes use one of the other Open method overloads). For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1849,7 +1849,7 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1905,9 +1905,9 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. - This method opens the package with a default attribute (to specify a different attribute use the method overload). + This method opens the package with a default attribute (to specify a different attribute use the method overload). For additional information, see the Open Packaging Conventions (OPC) specification available for download at . @@ -1976,7 +1976,7 @@ For more information about packages and package parts, see section 1.1 of the Op is the default package type that is used by the method. + is the default package type that is used by the method. For additional information, see the Open Packaging Conventions (OPC) specification available for download at . diff --git a/xml/System.IO.Packaging/PackageDigitalSignature.xml b/xml/System.IO.Packaging/PackageDigitalSignature.xml index 5232d3c3b62..5b608d351df 100644 --- a/xml/System.IO.Packaging/PackageDigitalSignature.xml +++ b/xml/System.IO.Packaging/PackageDigitalSignature.xml @@ -79,7 +79,7 @@ | Embedding option | Location | |-|-| ||In its own certificate in the package.

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

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

The X.509 certificate can be obtained through the property.| ||External to the package in a location known by both the application that creates the signature and the application that later uses the signature for validation.| ]]> @@ -153,7 +153,7 @@ provides access to the foundation class that performs type-specific signature cryptographic functions and serialization to and from the that hosts the signature. + provides access to the foundation class that performs type-specific signature cryptographic functions and serialization to and from the that hosts the signature. ]]> @@ -350,9 +350,9 @@ returns the X.509 certificate of the signer when the digital certificate is stored within the package (that is, when is or ). + returns the X.509 certificate of the signer when the digital certificate is stored within the package (that is, when is or ). - returns `null` when the X.509 certificate is not stored in the package (that is, when is ). + returns `null` when the X.509 certificate is not stored in the package (that is, when is ). ]]> @@ -389,11 +389,11 @@ property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. + The property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. - is based on the system time of the computer where the signing took place. + is based on the system time of the computer where the signing took place. - is not a "secure TimeStamp" and is not from trusted Time Stamp Authority. A secure TimeStamp must be obtained and applied through a trusted Time Stamp Authority. + is not a "secure TimeStamp" and is not from trusted Time Stamp Authority. A secure TimeStamp must be obtained and applied through a trusted Time Stamp Authority. ]]> diff --git a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml index b7ca59ddc77..8cfc9ba12ad 100644 --- a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml +++ b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml @@ -165,7 +165,7 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks If no X.509 certificate is specified in the call, this method opens a certificate selection dialog box that prompts the user to choose a certificate to use for signing. - Set the window handle in the property before calling to make the Certificate Selection Dialog modal to the given window. + Set the window handle in the property before calling to make the Certificate Selection Dialog modal to the given window. ]]> @@ -365,9 +365,9 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks The default hash algorithm identifier for the standard digital signature manager is ( - Secure Hash Algorithm version 1.0). - Unless explicitly set otherwise, this property gets the same value as . + Unless explicitly set otherwise, this property gets the same value as . - The property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible is encountered. When finished with the signature that uses a different hash algorithm, call to reset the property back to default. + The property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible is encountered. When finished with the signature that uses a different hash algorithm, call to reset the property back to default. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -441,7 +441,7 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks -The property does not perform signature validations. If signatures are present and is `true`, one or more of the signatures might not be valid. Call to confirm that the signatures are valid and have not changed. +The property does not perform signature validations. If signatures are present and is `true`, one or more of the signatures might not be valid. Call to confirm that the signatures are valid and have not changed. ## Examples @@ -496,7 +496,7 @@ The following example shows how to use the call contains no certificates. If no certificates are specified, will display a certificate selection dialog box that enables the user to choose which certificate to use for signing. + A certificate selection dialog box is presented only if a call contains no certificates. If no certificates are specified, will display a certificate selection dialog box that enables the user to choose which certificate to use for signing. ]]> @@ -532,7 +532,7 @@ The following example shows how to use the to persist all changes to the store. + This method also removes all X.509 certificates from the package. After removing all signatures and certificates, call to persist all changes to the store. ]]> @@ -576,7 +576,7 @@ The following example shows how to use the to persist the change to the store. + After removing a signature, call to persist the change to the store. ]]> @@ -638,9 +638,9 @@ The following example shows the steps to digitally sign a list of parts within a ## Remarks -To make the certificate selection dialog modal to a particular window, set the property before calling . +To make the certificate selection dialog modal to a particular window, set the property before calling . - will not prompt for certificates if there are none in the default certificate store. + will not prompt for certificates if there are none in the default certificate store. ## Examples @@ -872,11 +872,11 @@ The following example shows how to digitally sign a list of package parts. > [!NOTE] > The terms `Object`, `Manifest`, `Reference`, `SignatureProperties`, and `Transform` in the following two remarks refer to element types and tags defined by the W3C XML-Signature Syntax and Processing specification, see [https://www.w3.org/TR/xmldsig-core/](https://www.w3.org/TR/xmldsig-core/). - This and other method overloads use the current dictionary that defines a `Transform` to apply based on the package part . The Microsoft Open Packaging Conventions (OPC) specification currently allows only two valid `Transform` algorithms: C14 and C14N. The W3C XML-Signature Syntax and Processing standard does not allow empty `Manifest` tags. Also the Open Packaging Conventions specification requires a -specific `Object` tag that contains both `Manifest` and `SignatureProperties` tags. Each `Manifest` tag additionally also include at least one `Reference` tag. These tags require that each signature sign at least one (non-empty parts tag) or (non-empty `relationshipSelectors`) even if the signature is needed only to sign `signatureObjects` or `objectReferences`. + This and other method overloads use the current dictionary that defines a `Transform` to apply based on the package part . The Microsoft Open Packaging Conventions (OPC) specification currently allows only two valid `Transform` algorithms: C14 and C14N. The W3C XML-Signature Syntax and Processing standard does not allow empty `Manifest` tags. Also the Open Packaging Conventions specification requires a -specific `Object` tag that contains both `Manifest` and `SignatureProperties` tags. Each `Manifest` tag additionally also include at least one `Reference` tag. These tags require that each signature sign at least one (non-empty parts tag) or (non-empty `relationshipSelectors`) even if the signature is needed only to sign `signatureObjects` or `objectReferences`. - This method ignores the property associated with each defined in `objectReferences`. + This method ignores the property associated with each defined in `objectReferences`. - This overload provides support for generation of XML signatures that require custom `Object` tags. For any provided `Object` tag to be signed, a corresponding `Reference` tag must be provided with a uniform resource identifier (URI) that specifies the `Object` tag in local fragment syntax. For example if the `Object` tag has an ID of "myObject", the URI in the `Reference` tag would be "#myObject". For unsigned objects, no `Reference` is required. + This overload provides support for generation of XML signatures that require custom `Object` tags. For any provided `Object` tag to be signed, a corresponding `Reference` tag must be provided with a uniform resource identifier (URI) that specifies the `Object` tag in local fragment syntax. For example if the `Object` tag has an ID of "myObject", the URI in the `Reference` tag would be "#myObject". For unsigned objects, no `Reference` is required. ]]> @@ -916,7 +916,7 @@ The following example shows how to digitally sign a list of package parts. uniform resource identifier (URI) can vary by package because the name is not formally defined. While this implementation will generally use the same default value, the value returned by this property will reflect whatever origin is already present in the current . + The uniform resource identifier (URI) can vary by package because the name is not formally defined. While this implementation will generally use the same default value, the value returned by this property will reflect whatever origin is already present in the current . ]]> @@ -1023,7 +1023,7 @@ The following example shows how to digitally sign a list of package parts. ## Remarks -The default is "YYYY-MM-DDThh:mm:ss.sTZD". +The default is "YYYY-MM-DDThh:mm:ss.sTZD". Date/time formats follow the syntax of the [W3C Date and Time Formats specification](https://www.w3.org/TR/Note-datetime.html). The components shown in the following table must be present and use the syntax and punctuation as defined. @@ -1090,7 +1090,7 @@ Key: is executed. + During a sign operation the associated transform algorithm for each content type is applied before the is executed. Default content and transform mappings include: @@ -1181,7 +1181,7 @@ Key: ## Remarks -This method verifies only the digital signatures; it does not verify the related X.509 certificates. The method can be used to verify the X.509 certificates. +This method verifies only the digital signatures; it does not verify the related X.509 certificates. The method can be used to verify the X.509 certificates. ## Examples diff --git a/xml/System.IO.Packaging/PackagePart.xml b/xml/System.IO.Packaging/PackagePart.xml index de93e7ea231..d306926aa68 100644 --- a/xml/System.IO.Packaging/PackagePart.xml +++ b/xml/System.IO.Packaging/PackagePart.xml @@ -56,9 +56,9 @@ |Access|Description| |------------|-----------------| -||The URI of the part.| -||The MIME type of the content stream.| -||The content data stream of the part.| +||The URI of the part.| +||The MIME type of the content stream.| +||The content data stream of the part.| ]]> @@ -130,7 +130,7 @@ ## Remarks `partUri` must be valid URI formed in accordance with the [RFC 3986](https://tools.ietf.org/html/rfc3986) *Uniform Resource Identifier (URI) Generic Syntax* specification and the [Open Packaging Conventions](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) specification. - Use this constructor when the of the part is not immediately known and will be set later when is called. + Use this constructor when the of the part is not immediately known and will be set later when is called. By default, the property of the part is initialized to . @@ -338,9 +338,9 @@ is a read-only property that can be accessed only when the parent is open. + is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. ]]> @@ -388,9 +388,9 @@ is a read-only property that can be accessed only when the parent is open. + is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. The property is a MIME type formed in accordance with the [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616.html) *Hypertext Transfer Protocol - HTTP*, Section 3.7. The following table shows an example of the content MIME types used in XML Paper Specification (XPS) documents. @@ -439,7 +439,7 @@ In a part-relationship the source part is considered the "owner" of the relationship. When the source part is deleted, all the relationships owned by the part are also deleted. The process of creating or deleting the relationship does not physically alter the target part or resource in any way. - The method does not physically change either the source part, or the target part or resource in any way. + The method does not physically change either the source part, or the target part or resource in any way. The target of a relationship cannot be another relationship. @@ -509,7 +509,7 @@ In a part-relationship the source part is considered the "owner" of the relationship. When the source part is deleted, all the relationships owned by the part are also deleted. The process of creating or deleting the relationship does not physically alter the target part or resource in any way. - The method does not physically change either the source part, or the target part or resource in any way. + The method does not physically change either the source part, or the target part or resource in any way. The target of a relationship cannot be another relationship. @@ -622,7 +622,7 @@ A part-level relationship defines an association between this part and a target `id` must be a valid XML identifier. The `id` type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). - The method does not physically change either the source part, or the target part or resource in any way. + The method does not physically change either the source part, or the target part or resource in any way. The target of a relationship cannot be another relationship. @@ -718,9 +718,9 @@ A part-level relationship defines an association between this part and a target ## Remarks `id` must be a valid XML identifier. The `id` type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). - If the specified `id` does not match the for any of the relationships that are owned by this part, no relationship is deleted and no exception is thrown. + If the specified `id` does not match the for any of the relationships that are owned by this part, no relationship is deleted and no exception is thrown. - Other than deleting the specified relationship, the method does not physically change either this part or the target part. + Other than deleting the specified relationship, the method does not physically change either this part or the target part. ]]> @@ -778,9 +778,9 @@ A part-level relationship defines an association between this part and a target is a virtual method of the abstract base class. Implement this method only in derived types where the value for the content type cannot be provided at the time of construction, or if calculating the content type value is a nontrivial or costly operation. The return value must be a valid MIME content type. + is a virtual method of the abstract base class. Implement this method only in derived types where the value for the content type cannot be provided at the time of construction, or if calculating the content type value is a nontrivial or costly operation. The return value must be a valid MIME content type. - Derived classes can call to initialize the property of the derived class to a default value. After the property has been set it cannot be changed. + Derived classes can call to initialize the property of the derived class to a default value. After the property has been set it cannot be changed. ]]> @@ -829,7 +829,7 @@ A part-level relationship defines an association between this part and a target ## Remarks `id` must be a valid XML identifier. The `id` type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). - You can use the method to determine if a relationship with a specified is owned by this part. + You can use the method to determine if a relationship with a specified is owned by this part. ]]> @@ -1026,7 +1026,7 @@ A part-level relationship defines an association between this part and a target ## Remarks This method opens the content stream with of and permissions that are the same as the parent . - The overload method allows you to set a specific . + The overload method allows you to set a specific . ]]> @@ -1217,7 +1217,7 @@ A part-level relationship defines an association between this part and a target directly, but instead should call . + Applications should not call directly, but instead should call . ]]> @@ -1267,9 +1267,9 @@ A part-level relationship defines an association between this part and a target is a read-only property that can be accessed only when the parent is open. + is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the parent for the part cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the parent for the part cannot be changed. ]]> @@ -1378,9 +1378,9 @@ A part-level relationship defines an association between this part and a target is a read-only property that can be accessed only when the parent is open. + is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the of the part cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the of the part cannot be changed. ]]> diff --git a/xml/System.IO.Packaging/PackagePartCollection.xml b/xml/System.IO.Packaging/PackagePartCollection.xml index 6e03fec2372..36556cc82f5 100644 --- a/xml/System.IO.Packaging/PackagePartCollection.xml +++ b/xml/System.IO.Packaging/PackagePartCollection.xml @@ -50,11 +50,11 @@ Represents a collection of objects. - class has no public constructor. This class is created and returned by the method. - + class has no public constructor. This class is created and returned by the method. + ]]> @@ -97,11 +97,11 @@ Returns an enumerator for iterating through the parts in the collection. An enumerator for iterating through the elements in the collection. - method or method is called. - + method or method is called. + ]]> @@ -149,11 +149,11 @@ Returns an enumerator that iterates through the collection. An object that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -201,11 +201,11 @@ For a description of this member, see . An object that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.IO.Packaging/PackageProperties.xml b/xml/System.IO.Packaging/PackageProperties.xml index 9b661ca87dd..3358a1563b1 100644 --- a/xml/System.IO.Packaging/PackageProperties.xml +++ b/xml/System.IO.Packaging/PackageProperties.xml @@ -129,7 +129,7 @@ value is typically used as part of the application user interface (UI) to create labels for navigation controls. + The value is typically used as part of the application user interface (UI) to create labels for navigation controls. ]]> @@ -173,7 +173,7 @@ values include "Draft", "Reviewed", and "Final". + Example values include "Draft", "Reviewed", and "Final". ]]> @@ -216,7 +216,7 @@ values include "Whitepaper", "Security Bulletin", and "Exam". + Example values include "Whitepaper", "Security Bulletin", and "Exam". This property is distinct from Multipurpose Internet Mail Extensions (MIME) content types as defined in RFC 2616. @@ -336,7 +336,7 @@ may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text account of the content. + The may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text account of the content. ]]> @@ -390,10 +390,10 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.IO.Packaging/PackageRelationship.xml b/xml/System.IO.Packaging/PackageRelationship.xml index d9297980e00..3391ec60b76 100644 --- a/xml/System.IO.Packaging/PackageRelationship.xml +++ b/xml/System.IO.Packaging/PackageRelationship.xml @@ -58,8 +58,8 @@ | `Create` method | Description | |-|-| -|.|Creates a "package-level" relationship-from a package to a specified part or external resource.| -|.|Creates a "part-level" relationship-from one part to another part or external resource.| +|.|Creates a "package-level" relationship-from a package to a specified part or external resource.| +|.|Creates a "part-level" relationship-from one part to another part or external resource.| The source package or part is identified by the property of the relationship. The target part or external resource is identified by the property of the relationship. @@ -117,11 +117,11 @@ property string is unique for all relationships owned by the package or part. + The property string is unique for all relationships owned by the package or part. - The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created, the cannot be changed. + The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created, the cannot be changed. - The property string is a valid XML identifier. The type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). + The property string is a valid XML identifier. The type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). ]]> @@ -220,9 +220,9 @@ is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created, the cannot be changed. + The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created, the cannot be changed. - is defined in a URI-like syntax and identifies the role of the relationship. For example, `"http://schemas.microsoft.com/xps/2005/06/required-resource"` identifies the relationship to a target part that is a "required-resource." + is defined in a URI-like syntax and identifies the role of the relationship. For example, `"http://schemas.microsoft.com/xps/2005/06/required-resource"` identifies the relationship to a target part that is a "required-resource." **Package-Wide Relationship Types** @@ -277,9 +277,9 @@ , returns a URI of "/". + If the relationship is owned by a , returns a URI of "/". - If the relationship is owned by a , returns the URI of the part. + If the relationship is owned by a , returns the URI of the part. ]]> @@ -328,13 +328,13 @@ is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created the cannot be changed. + The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created the cannot be changed. - When is , the MUST be a relative reference. For a package-level relationship, the relative reference of the is resolved relative to the pack URI of the source package that owns and contains the relationship. (Example source package pack URI: "pack://http:,,www.adatum.com,files,datapak.package/".) For a part-level relationship, the is resolved relative to the source part that owns the relationship ( is interpreted relative to ). + When is , the MUST be a relative reference. For a package-level relationship, the relative reference of the is resolved relative to the pack URI of the source package that owns and contains the relationship. (Example source package pack URI: "pack://http:,,www.adatum.com,files,datapak.package/".) For a part-level relationship, the is resolved relative to the source part that owns the relationship ( is interpreted relative to ). - When is , the can be either a relative reference or a fully qualified URI. If the is a relative reference, the reference is interpreted as relative to the location of the that contains this relationship. + When is , the can be either a relative reference or a fully qualified URI. If the is a relative reference, the reference is interpreted as relative to the location of the that contains this relationship. - For more information about see Section 1.3.3 "Relationship Markup" of the *Open Packaging Conventions* specification available for download at . + For more information about see Section 1.3.3 "Relationship Markup" of the *Open Packaging Conventions* specification available for download at . ]]> @@ -384,13 +384,13 @@ is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created the cannot be changed. + The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created the cannot be changed. - When is , the MUST be a relative reference. For a package-level relationship, the relative reference of the is resolved relative to the pack URI of the source package that owns and contains the relationship. (Example source package pack URI: "pack://http:,,www.adatum.com,files,datapak.package/".) For a part-level relationship, the is resolved relative to the source part that owns the relationship ( is interpreted relative to ). + When is , the MUST be a relative reference. For a package-level relationship, the relative reference of the is resolved relative to the pack URI of the source package that owns and contains the relationship. (Example source package pack URI: "pack://http:,,www.adatum.com,files,datapak.package/".) For a part-level relationship, the is resolved relative to the source part that owns the relationship ( is interpreted relative to ). - When is , the can be either a relative reference or a fully qualified URI. If the is a relative reference, the reference is interpreted as relative to the location of the that contains this relationship. + When is , the can be either a relative reference or a fully qualified URI. If the is a relative reference, the reference is interpreted as relative to the location of the that contains this relationship. - For more information about see Section 1.3.3 "Relationship Markup" of the *Open Packaging Conventions* specification available for download at . + For more information about see Section 1.3.3 "Relationship Markup" of the *Open Packaging Conventions* specification available for download at . ]]> diff --git a/xml/System.IO.Packaging/PackageRelationshipCollection.xml b/xml/System.IO.Packaging/PackageRelationshipCollection.xml index 272a9fc07a7..cd4599fc777 100644 --- a/xml/System.IO.Packaging/PackageRelationshipCollection.xml +++ b/xml/System.IO.Packaging/PackageRelationshipCollection.xml @@ -50,19 +50,19 @@ Represents a collection of elements that are owned by a given or the . - class has no public constructor. This class is created and returned by the following methods. - -- **Package**. - -- **Package**. - -- **PackagePart**. - -- **PackagePart**. - + class has no public constructor. This class is created and returned by the following methods. + +- **Package**. + +- **Package**. + +- **PackagePart**. + +- **PackagePart**. + ]]> @@ -107,19 +107,19 @@ Returns an enumerator for iterating through the relationships in the collection. An enumerator for iterating through the elements in the collection. - - -- **Package**. - -- **PackagePart**. - -- **PackagePart**. - + + +- **Package**. + +- **PackagePart**. + +- **PackagePart**. + ]]> diff --git a/xml/System.IO.Packaging/PackageRelationshipSelector.xml b/xml/System.IO.Packaging/PackageRelationshipSelector.xml index af2456b6964..155a4dbea00 100644 --- a/xml/System.IO.Packaging/PackageRelationshipSelector.xml +++ b/xml/System.IO.Packaging/PackageRelationshipSelector.xml @@ -52,7 +52,7 @@ is used by the method of the class to specify a list of parts to be signed. + is used by the method of the class to specify a list of parts to be signed. is used by the property of the class to obtain a list of parts that have been signed with the given digital signature. diff --git a/xml/System.IO.Packaging/PackageStore.xml b/xml/System.IO.Packaging/PackageStore.xml index 5738e518486..d69bd723caf 100644 --- a/xml/System.IO.Packaging/PackageStore.xml +++ b/xml/System.IO.Packaging/PackageStore.xml @@ -42,15 +42,15 @@ 3. Accessing packages that are created and stored in a . - To improve performance and minimize the overhead of repeated file open/close operations, the is used to manage instances of packages accessed by and directly by the application. When accessing data in a package, the address of a requested is first checked to see if the package is already defined and open in the . If the package is defined as open in the , requested parts can be accessed directly without repeatedly opening and closing the package for each request. + To improve performance and minimize the overhead of repeated file open/close operations, the is used to manage instances of packages accessed by and directly by the application. When accessing data in a package, the address of a requested is first checked to see if the package is already defined and open in the . If the package is defined as open in the , requested parts can be accessed directly without repeatedly opening and closing the package for each request. - If your application opens a package with , can be called to add the package to the . should later be called to remove the package from the prior to calling . + If your application opens a package with , can be called to add the package to the . should later be called to remove the package from the prior to calling . - XPS packages opened with an constructor are automatically added and removed from the when the document is created and disposed. (You do not need to call or separately for XPS packages opened with constructors.) + XPS packages opened with an constructor are automatically added and removed from the when the document is created and disposed. (You do not need to call or separately for XPS packages opened with constructors.) The file I/O permissions of a package accessed through the remains the same as the I/O permissions set on the package when it is opened. The only provides references to the packages that have been added the store. It is up to the application to correctly open, update, and close each package. - Packages added to the can be accessed in multithreaded environments when they are used in combination with a XAML parser such as . When operating in a multithreaded environment, the application must lock the package before access. + Packages added to the can be accessed in multithreaded environments when they are used in combination with a XAML parser such as . When operating in a multithreaded environment, the application must lock the package before access. ]]> @@ -95,14 +95,14 @@ ## Remarks `uri` defines the package's key URI that is compared when you call . - If the `uri` matches the for a in a call, the package defined in the is used to access the requested part. + If the `uri` matches the for a in a call, the package defined in the is used to access the requested part. - If the `uri` does not match the for a in a call, the package with the specified URI is opened to access the requested part. + If the `uri` does not match the for a in a call, the package with the specified URI is opened to access the requested part. **Security Note** This method demands for all custom (non-) types. ## Examples - The following example shows how to use the method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewdecrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewdecrypt"::: @@ -153,12 +153,12 @@ ## Remarks -`uri` is matched to the URIs specified in the method call. +`uri` is matched to the URIs specified in the method call. **Security Note** This method demands for all custom (non-) types. ## Examples - The following example shows how to use the method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopendoc"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopendoc"::: @@ -207,12 +207,12 @@ ## Remarks -`uri` is matched to the URIs specified in the method call. +`uri` is matched to the URIs specified in the method call. **Security Note** This method demands for all custom (non-) types. ## Examples - The following example shows how to use the method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewclosedoc"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewclosedoc"::: diff --git a/xml/System.IO.Packaging/RightsManagementInformation.xml b/xml/System.IO.Packaging/RightsManagementInformation.xml index fe143a7c163..0359b25b056 100644 --- a/xml/System.IO.Packaging/RightsManagementInformation.xml +++ b/xml/System.IO.Packaging/RightsManagementInformation.xml @@ -157,7 +157,7 @@ only returns those use licenses that are currently embedded in the package. It does not include any other use licenses that the application might have acquired separately from a rights management server but that are not yet embedded in the package. + only returns those use licenses that are currently embedded in the package. It does not include any other use licenses that the application might have acquired separately from a rights management server but that are not yet embedded in the package. ]]> @@ -196,7 +196,7 @@ method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopenpkg"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: @@ -242,7 +242,7 @@ method. + The following example shows how to use the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopenpkg"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: @@ -290,7 +290,7 @@ can contain only one . Each call to will overwrite any prior contained in the . + Each can contain only one . Each call to will overwrite any prior contained in the . ]]> @@ -335,14 +335,14 @@ for the specified user has been saved, it can be retrieved through the method and from the collection returned by . + After the for the specified user has been saved, it can be retrieved through the method and from the collection returned by . - A can store the rights information for multiple content users. Each ContentUser can have at most one . If is called to store a new for a that already has a , the previous license will be overwritten with the new license. + A can store the rights information for multiple content users. Each ContentUser can have at most one . If is called to store a new for a that already has a , the previous license will be overwritten with the new license. ## Examples - The following example shows how to use of the method. + The following example shows how to use of the method. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: diff --git a/xml/System.IO.Packaging/StorageInfo.xml b/xml/System.IO.Packaging/StorageInfo.xml index 123a38f2074..c5f7ad5ca41 100644 --- a/xml/System.IO.Packaging/StorageInfo.xml +++ b/xml/System.IO.Packaging/StorageInfo.xml @@ -75,11 +75,11 @@ Creates a new stream with a given name. The new stream with the specified . - method creates a new stream with default settings set to CompressionOption. and EncryptionOption.. - + method creates a new stream with default settings set to CompressionOption. and EncryptionOption.. + ]]> @@ -222,11 +222,11 @@ The name of the sub-store to delete. Deletes a specified sub-store. - also recursively deletes all descendant sub-stores. - + also recursively deletes all descendant sub-stores. + ]]> The parameter is . @@ -296,13 +296,13 @@ Returns an array of the instances that are currently contained in this store. An array of the objects, each pointing to an I/O steam defined within this store. - will always return a array, but the array may be empty (zero-length) if there are no streams defined in the store. - - provides a snapshot of the streams currently defined in the store. The individual objects will reflect the updated state of their respective streams, but the returned array will not be updated with any additions or deletions. Call again to obtain an updated array as streams added or deleted to the store. - + will always return a array, but the array may be empty (zero-length) if there are no streams defined in the store. + + provides a snapshot of the streams currently defined in the store. The individual objects will reflect the updated state of their respective streams, but the returned array will not be updated with any additions or deletions. Call again to obtain an updated array as streams added or deleted to the store. + ]]> @@ -375,13 +375,13 @@ Returns an array of the child sub-stores that are currently contained in this store. An array of objects, each pointing to a sub-store defined within this store. - will always return a array, but the array may be empty (zero-length) if there are no sub-stores. - - provides a snapshot of the sub-stores currently defined in this store. The individual objects will reflect the updated state of their respective stores, but the returned array will not be updated with any additions or deletions. Call again to obtain an updated array as sub-stores added or deleted to the store. - + will always return a array, but the array may be empty (zero-length) if there are no sub-stores. + + provides a snapshot of the sub-stores currently defined in this store. The individual objects will reflect the updated state of their respective stores, but the returned array will not be updated with any additions or deletions. Call again to obtain an updated array as sub-stores added or deleted to the store. + ]]> @@ -416,11 +416,11 @@ Gets the name of the store. The name of this store. - method and cannot be changed after created. - + method and cannot be changed after created. + ]]> diff --git a/xml/System.IO.Packaging/StreamInfo.xml b/xml/System.IO.Packaging/StreamInfo.xml index e90c64cd6ee..a63e9b23633 100644 --- a/xml/System.IO.Packaging/StreamInfo.xml +++ b/xml/System.IO.Packaging/StreamInfo.xml @@ -60,8 +60,7 @@ has been called on the stream, the property returns CompressionOption.. +If has been called on the stream, the property returns CompressionOption.. ]]> @@ -98,8 +97,7 @@ has been called on the stream, the property returns EncryptionOption.. +If has been called on the stream, the property returns EncryptionOption.. ]]> @@ -148,7 +146,7 @@ method (without parameters), opens the stream in file mode with the default storage root . + This method (without parameters), opens the stream in file mode with the default storage root . ]]> @@ -189,7 +187,7 @@ method opens the stream with the default storage root . + This method opens the stream with the default storage root . ]]> @@ -261,8 +259,7 @@ has been called on the stream, the property returns an empty string. +If has been called on the stream, the property returns an empty string. ]]> diff --git a/xml/System.IO.Packaging/TargetMode.xml b/xml/System.IO.Packaging/TargetMode.xml index 67e3446631f..54f6bf080f1 100644 --- a/xml/System.IO.Packaging/TargetMode.xml +++ b/xml/System.IO.Packaging/TargetMode.xml @@ -42,13 +42,13 @@ Specifies whether the target of a is inside or outside the . - (`Internal`), the relationship is always a relative URI. - - If the target is outside the (`External`), the relationship can be either relative to the current location of the package or an absolute URI. - + (`Internal`), the relationship is always a relative URI. + + If the target is outside the (`External`), the relationship can be either relative to the current location of the package or an absolute URI. + ]]> diff --git a/xml/System.IO.Packaging/ZipPackage.xml b/xml/System.IO.Packaging/ZipPackage.xml index 8ab1e132dcb..fed9fbe0854 100644 --- a/xml/System.IO.Packaging/ZipPackage.xml +++ b/xml/System.IO.Packaging/ZipPackage.xml @@ -52,7 +52,7 @@ method uses containers by default. + The **Package**. method uses containers by default. ## Examples This example shows how to create a basic . diff --git a/xml/System.IO.Pipelines/PipeReader.xml b/xml/System.IO.Pipelines/PipeReader.xml index 7ab5cdadbc1..9295097256d 100644 --- a/xml/System.IO.Pipelines/PipeReader.xml +++ b/xml/System.IO.Pipelines/PipeReader.xml @@ -63,7 +63,7 @@ ## Remarks -The memory for the consumed data will be released and no longer available. The previously returned from must not be accessed after this call. The examined data communicates to the pipeline when it should signal more data is available. +The memory for the consumed data will be released and no longer available. The previously returned from must not be accessed after this call. The examined data communicates to the pipeline when it should signal more data is available. ]]> diff --git a/xml/System.IO.Pipelines/PipeWriter.xml b/xml/System.IO.Pipelines/PipeWriter.xml index 652769ceea0..df01bc61d4a 100644 --- a/xml/System.IO.Pipelines/PipeWriter.xml +++ b/xml/System.IO.Pipelines/PipeWriter.xml @@ -338,7 +338,7 @@ There is no guarantee that successive calls will return the same buffer or the s This method never returns , but it throws an if the requested buffer size is not available. -You must request a new buffer after calling to continue writing more data; you cannot write to a previously acquired buffer. +You must request a new buffer after calling to continue writing more data; you cannot write to a previously acquired buffer. ]]> diff --git a/xml/System.IO.Pipes/AnonymousPipeClientStream.xml b/xml/System.IO.Pipes/AnonymousPipeClientStream.xml index bc77aa82015..d2e1119b019 100644 --- a/xml/System.IO.Pipes/AnonymousPipeClientStream.xml +++ b/xml/System.IO.Pipes/AnonymousPipeClientStream.xml @@ -61,7 +61,7 @@ Anonymous pipes do not support the read mode. - The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is passed to the constructor as the `pipeHandleAsString` parameter. + The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is passed to the constructor as the `pipeHandleAsString` parameter. On Windows, asynchronous (overlapped) read and write operations aren't supported by anonymous pipes (see [Anonymous pipe operations](https://learn.microsoft.com/windows/win32/ipc/anonymous-pipe-operations)). The class will still schedule work on the thread pool on Windows platforms so asynchronous operations work, but cancellation of those operations isn't supported. ## Examples @@ -69,7 +69,7 @@ The following example sends a string from a parent process to a child process by using anonymous pipes. This example creates an object in a parent process with a value of . It also creates an object in a child process with a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. This example is for the client process, which is started by the server process. Name the resulting executable from the client code `pipeClient.exe` and copy it to the same directory as the server executable when you run this example. For the entire code example, including the code for both the pipe client and server, see [How to: Use Anonymous Pipes for Local Interprocess Communication](/dotnet/standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication). - + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeClientStream/Overview/Program.cs"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Pipes/AnonymousPipeClientStream/Overview/program.vb"::: @@ -470,7 +470,7 @@ Anonymous pipes do not support object is created in a child process and the is displayed to the console. +The following example sends a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a child process and the is displayed to the console. :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeClientStream/Overview/Program.cs"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Pipes/AnonymousPipeClientStream/Overview/program.vb"::: diff --git a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml index 5790376bf0a..3c87d304522 100644 --- a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml +++ b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml @@ -61,9 +61,9 @@ Anonymous pipes do not support the read mode. - The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is then passed to the constructor as the `pipeHandleAsString` parameter. + The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is then passed to the constructor as the `pipeHandleAsString` parameter. - The object must dispose the client handle using the method in order to be notified when the client exits. + The object must dispose the client handle using the method in order to be notified when the client exits. ## Examples @@ -548,7 +548,7 @@ The following example sends a string from a parent process to a child process us method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. + The method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. ]]> @@ -653,7 +653,7 @@ The following example sends a string from a parent process to a child process us method should be called after the client handle has been passed to the client. If this method is not called, the object will not receive notice when the client disposes of its object. + The method should be called after the client handle has been passed to the client. If this method is not called, the object will not receive notice when the client disposes of its object. @@ -757,7 +757,7 @@ The following example sends a string from a parent process to a child process us method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. + The method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. diff --git a/xml/System.IO.Pipes/NamedPipeClientStream.xml b/xml/System.IO.Pipes/NamedPipeClientStream.xml index 98e3d9c0cb7..ff5e648da44 100644 --- a/xml/System.IO.Pipes/NamedPipeClientStream.xml +++ b/xml/System.IO.Pipes/NamedPipeClientStream.xml @@ -850,11 +850,11 @@ method with an infinite time-out value. + This method calls the method with an infinite time-out value. - This method waits for a pipe instance to become available. might return before is called from the object, but will not return until has returned. + This method waits for a pipe instance to become available. might return before is called from the object, but will not return until has returned. - Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . + Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . @@ -921,9 +921,9 @@ might return before is called from the , but will not return until has returned. You set the `timeout` parameter to to specify an infinite time-out value. + This method waits for a pipe instance to become available. might return before is called from the , but will not return until has returned. You set the `timeout` parameter to to specify an infinite time-out value. - Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . + Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . ]]> diff --git a/xml/System.IO.Pipes/NamedPipeServerStream.xml b/xml/System.IO.Pipes/NamedPipeServerStream.xml index 9c3ca8d1d53..529473b149d 100644 --- a/xml/System.IO.Pipes/NamedPipeServerStream.xml +++ b/xml/System.IO.Pipes/NamedPipeServerStream.xml @@ -1044,9 +1044,9 @@ This example is for the server process, which uses the . + This is the asynchronous equivalent of . - must be called exactly once for every call to . + must be called exactly once for every call to . ]]> @@ -1112,7 +1112,7 @@ This example is for the server process, which uses the method will block until all the sent characters have been read unless the transmission mode of the pipe is set to and the buffer size is set in the constructor that created the object. In this case, not all of the messages will be received. Calling causes the server to block until all the data has been read from the pipe. + Calling the method will block until all the sent characters have been read unless the transmission mode of the pipe is set to and the buffer size is set in the constructor that created the object. In this case, not all of the messages will be received. Calling causes the server to block until all the data has been read from the pipe. ]]> @@ -1179,7 +1179,7 @@ This example is for the server process, which uses the must be called exactly once for every call to . + must be called exactly once for every call to . ]]> @@ -1284,7 +1284,7 @@ This example is for the server process, which uses the method returns `null` if the client has not yet written to the pipe or if the connected client did not connect with a of . + The method returns `null` if the client has not yet written to the pipe or if the connected client did not connect with a of . @@ -1564,7 +1564,7 @@ This example is for the server process, which uses the or . + Because it is asynchronous, this method returns immediately, but the connection process is completed when the client calls or . This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1618,9 +1618,9 @@ This example is for the server process, which uses the or . + Because it is asynchronous, this method returns immediately, but the connection process is completed when the client calls or . - Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. + Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.IO.Pipes/PipeSecurity.xml b/xml/System.IO.Pipes/PipeSecurity.xml index 65014e1253b..bdbe6df5573 100644 --- a/xml/System.IO.Pipes/PipeSecurity.xml +++ b/xml/System.IO.Pipes/PipeSecurity.xml @@ -48,7 +48,7 @@ Use the class to retrieve, add, or change the access rules that represent the DACL and SACL of a pipe. - To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. + To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. ]]> @@ -88,9 +88,9 @@ ## Remarks This constructor creates an empty object that is not based on an existing pipe. You can then populate the object with access control information and apply it to a pipe. - You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. + You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. - To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. + To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. ]]> @@ -286,7 +286,7 @@ method adds a new rule to the list of rules that a object contains. If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object that is created using the value supersedes an object that is created using the value. + The method adds a new rule to the list of rules that a object contains. If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object that is created using the value supersedes an object that is created using the value. ]]> @@ -332,9 +332,9 @@ method adds a new audit rule to the list of rules that a object contains. + The method adds a new audit rule to the list of rules that a object contains. - If an audit rule already exists for the specified rule, the method will still add the rule. + If an audit rule already exists for the specified rule, the method will still add the rule. ]]> @@ -585,7 +585,7 @@ method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. + The method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. ]]> @@ -631,7 +631,7 @@ method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. + The method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. ]]> @@ -679,7 +679,7 @@ method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. + The method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. ]]> @@ -725,7 +725,7 @@ method removes all audit rules for the specified user. It ignores all values in the object except the user account. + The method removes all audit rules for the specified user. It ignores all values in the object except the user account. ]]> @@ -771,7 +771,7 @@ method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. + The method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. ]]> @@ -817,7 +817,7 @@ method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. + The method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. ]]> @@ -863,7 +863,7 @@ method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. + The method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. ]]> @@ -909,7 +909,7 @@ method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. + The method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. ]]> diff --git a/xml/System.IO.Pipes/PipeStream.xml b/xml/System.IO.Pipes/PipeStream.xml index 9a1f1cd5212..0007754fc28 100644 --- a/xml/System.IO.Pipes/PipeStream.xml +++ b/xml/System.IO.Pipes/PipeStream.xml @@ -262,11 +262,11 @@ object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . Use the property to determine whether the current object supports read operations. - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. ]]> @@ -361,11 +361,11 @@ must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . Use the property to determine whether the current object supports write operations. - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. ]]> @@ -741,9 +741,9 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. -When the disposing parameter is `true`, this method releases all resources held by any managed objects that this object references. This method invokes the method of each referenced object. +When the disposing parameter is `true`, this method releases all resources held by any managed objects that this object references. This method invokes the method of each referenced object. ]]> @@ -808,13 +808,13 @@ When the disposing parameter is `true`, this method releases all resources held . + This method returns the number of bytes read into the byte array specified by the earlier call to . - Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . Use the property to determine whether the current object supports read operations. - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. ]]> @@ -876,11 +876,11 @@ When the disposing parameter is `true`, this method releases all resources held must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . Use the property to determine whether the current object supports write operations. - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code the calls method. + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code the calls method. ]]> @@ -940,7 +940,7 @@ When the disposing parameter is `true`, this method releases all resources held method is not supported in the class and does nothing when it is called. + The method is not supported in the class and does nothing when it is called. ]]> @@ -1079,7 +1079,7 @@ When the disposing parameter is `true`, this method releases all resources held is 0, the buffer size is allocated as needed. + If is 0, the buffer size is allocated as needed. ]]> @@ -1364,7 +1364,7 @@ When the disposing parameter is `true`, this method releases all resources held property was set to by the most recent call to or . + This property is relevant if the pipe's property was set to by the most recent call to or . ]]> @@ -1479,7 +1479,7 @@ When the disposing parameter is `true`, this method releases all resources held is 0, the buffer size is allocated as needed. + If is 0, the buffer size is allocated as needed. ]]> @@ -1579,7 +1579,7 @@ When the disposing parameter is `true`, this method releases all resources held Use the property to determine whether the current object supports read operations. -Use the method to read asynchronously from the current stream. +Use the method to read asynchronously from the current stream. This method reads a maximum of `buffer.Length` bytes from the current stream and stores them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. @@ -1668,12 +1668,12 @@ The pipe handle has not been set. (Did your method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. +The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports reading. @@ -2059,7 +2059,7 @@ The pipe handle has not been set. (Did your method is not supported in pipes and raises a when it is called. + The method is not supported in pipes and raises a when it is called. ]]> @@ -2161,7 +2161,7 @@ The pipe handle has not been set. (Did your class does not support the method. + The class does not support the method. ]]> @@ -2282,7 +2282,7 @@ The pipe handle has not been set. (Did your method blocks until the other end of the pipe has read all sent bytes. + The method blocks until the other end of the pipe has read all sent bytes. ]]> @@ -2329,7 +2329,7 @@ The pipe handle has not been set. (Did your property to determine whether the current object supports write operations. - For asynchronous write operations, see and . + For asynchronous write operations, see and . ]]> @@ -2467,7 +2467,7 @@ The pipe handle has not been set. (Did your method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. +The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports writing. diff --git a/xml/System.IO.Ports/SerialPort.xml b/xml/System.IO.Ports/SerialPort.xml index 3139a1e1c18..937f3f1c03e 100644 --- a/xml/System.IO.Ports/SerialPort.xml +++ b/xml/System.IO.Ports/SerialPort.xml @@ -43,9 +43,9 @@ ## Remarks Use this class to control a serial port file resource. This class provides synchronous and event-driven I/O, access to pin and break states, and access to serial driver properties. Additionally, the functionality of this class can be wrapped in an internal object, accessible through the property, and passed to classes that wrap or use streams. - The class supports the following encodings: , , , , and any encoding defined in mscorlib.dll where the code page is less than 50000 or the code page is 54936. You can use alternate encodings, but you must use the or method and perform the encoding yourself. + The class supports the following encodings: , , , , and any encoding defined in mscorlib.dll where the code page is less than 50000 or the code page is 54936. You can use alternate encodings, but you must use the or method and perform the encoding yourself. - You use the method to retrieve the valid ports for the current computer. + You use the method to retrieve the valid ports for the current computer. If a object becomes blocked during a read operation, do not abort the thread. Instead, either close the base stream or dispose of the object. @@ -394,9 +394,9 @@ ## Remarks Use this property for explicit asynchronous I/O operations or to pass the object to a wrapper class such as . - Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. + Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. - Due to the inaccessibility of the wrapped file handle, the and properties are not supported, and the and methods are not supported. + Due to the inaccessibility of the wrapped file handle, the and properties are not supported, and the and methods are not supported. ]]> @@ -516,7 +516,7 @@ object while is `true`. + The break signal state occurs when a transmission is suspended and the line is placed in a break state (all low, no stop bit) until released. To enter a break state, set this property to `true`. If the port is already in a break state, setting this property again to `true` does not result in an exception. It is not possible to write to the object while is `true`. ]]> @@ -696,9 +696,9 @@ object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. + Calling this method closes the object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. - The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. + The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. @@ -873,7 +873,7 @@ The event is not guaranteed to be raised for every byte received. Use the property to determine how much data is left to be read in the buffer. - The event is raised on a secondary thread when data is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + The event is raised on a secondary thread when data is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1056,7 +1056,7 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -1265,7 +1265,7 @@ If a parity error occurs on the trailing byte of a stream, an extra byte will be added to the input buffer with a value of 126. - The event is raised on a secondary thread when an error is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + The event is raised on a secondary thread when an error is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1301,16 +1301,16 @@ is not specified. + The order of port names returned from is not specified. - Use the method to query the current computer for a list of valid serial port names. For example, you can use this method to determine whether COM1 and COM2 are valid serial ports for the current computer. + Use the method to query the current computer for a list of valid serial port names. For example, you can use this method to determine whether COM1 and COM2 are valid serial ports for the current computer. - The port names are obtained from the system registry (for example, HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\SERIALCOMM). If the registry contains stale or otherwise incorrect data then the method will return incorrect data. + The port names are obtained from the system registry (for example, HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\SERIALCOMM). If the registry contains stale or otherwise incorrect data then the method will return incorrect data. ## Examples - The following code example uses the method to display serial port names to the console. + The following code example uses the method to display serial port names to the console. :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/SerialPort/GetPortNames/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/SerialPort/GetPortNames/example.vb" id="Snippet1"::: @@ -1365,9 +1365,9 @@ object is instructed to stop sending data when there is at least (-1024) bytes in the buffer. The device is instructed to start sending data again when there are 1024 or fewer bytes in the buffer. If the device is sending data in blocks that are larger than 1024 bytes, this may cause the buffer to overflow. + When handshaking is used, the device connected to the object is instructed to stop sending data when there is at least (-1024) bytes in the buffer. The device is instructed to start sending data again when there are 1024 or fewer bytes in the buffer. If the device is sending data in blocks that are larger than 1024 bytes, this may cause the buffer to overflow. - If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. + If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. @@ -1414,7 +1414,7 @@ and properties. + This value is used with the and properties. ]]> @@ -1505,7 +1505,7 @@ and methods. By default the end-of-line value is a line feed character (`\n` in C#, in Visual Basic). You would change this to a different value if the particular serial device you're working with uses a different value for the same purpose. + This property determines what value (byte) defines the end of a line for the and methods. By default the end-of-line value is a line feed character (`\n` in C#, in Visual Basic). You would change this to a different value if the particular serial device you're working with uses a different value for the same purpose. ]]> @@ -1542,7 +1542,7 @@ ## Remarks Only one open connection can exist per object. - The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. + The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. @@ -1731,11 +1731,11 @@ ## Remarks Serial pin changed events can be caused by any of the items in the enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. As part of the event, the new value of the pin is set. - The event is raised when a object enters the , but not when the port exits the . This behavior does not apply to other values in the enumeration. + The event is raised when a object enters the , but not when the port exits the . This behavior does not apply to other values in the enumeration. , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. - The event is raised on a secondary thread. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. + The event is raised on a secondary thread. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1788,7 +1788,7 @@ method. + A list of valid port names can be obtained using the method. @@ -1861,7 +1861,7 @@ Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. - The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. + The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. ]]> @@ -1914,7 +1914,7 @@ Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many characters are available to read. The property can indicate that there are characters to read, but these characters might not be accessible to the stream contained in the property because they have been buffered to the class. - The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. + The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. ]]> @@ -2016,7 +2016,7 @@ ## Remarks This method reads one byte. - Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] > Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. @@ -2061,7 +2061,7 @@ ## Remarks This method reads one complete character based on the encoding. - Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. + Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] > Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. @@ -2104,7 +2104,7 @@ object as a string. This method does not use a time-out. Note that this method can leave trailing lead bytes in the internal buffer, which makes the value greater than zero. + This method returns the contents of the stream and internal buffer of the object as a string. This method does not use a time-out. Note that this method can leave trailing lead bytes in the internal buffer, which makes the value greater than zero. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. @@ -2144,9 +2144,9 @@ value, the value is removed from the input buffer. + Note that while this method does not return the value, the value is removed from the input buffer. - By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. + By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. @@ -2221,7 +2221,7 @@ > [!NOTE] > Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - This property does not affect the method of the stream returned by the property. + This property does not affect the method of the stream returned by the property. @@ -2438,7 +2438,7 @@ is . + The default value for is . The value is not supported. @@ -2506,9 +2506,9 @@ ## Remarks Use this method when you want to write a string as output to a serial port. - If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. + If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. - By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . + By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . ]]> @@ -2554,7 +2554,7 @@ ## Remarks Use this method when you want to write to a byte buffer to create output to a serial port. - If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. + If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. ]]> The passed is . @@ -2601,9 +2601,9 @@ ## Remarks Use this method when you want to write to a character buffer to create output to a serial port. - If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. + If there are too many bytes in the output buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. - By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . + By default, uses to encode the characters. encodes all characters greater than 127 as (char)63 or '?'. To support additional characters in that range, set to , , or . ]]> @@ -2699,9 +2699,9 @@ is set to then the object may raise a while it waits for the device to be ready to accept more data. + If there are too many bytes in the input buffer and is set to then the object may raise a while it waits for the device to be ready to accept more data. - The written output includes the string. + The written output includes the string. @@ -2768,7 +2768,7 @@ > [!NOTE] > Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - This property does not affect the method of the stream returned by the property. + This property does not affect the method of the stream returned by the property. diff --git a/xml/System.IO/BinaryReader.xml b/xml/System.IO/BinaryReader.xml index bc885d54894..14cd7ae2e21 100644 --- a/xml/System.IO/BinaryReader.xml +++ b/xml/System.IO/BinaryReader.xml @@ -90,12 +90,12 @@ class provides methods that simplify reading primitive data types from a stream. For example, you can use the method to read the next byte as a Boolean value and advance the current position in the stream by one byte. The class includes read methods that support different data types. + The class provides methods that simplify reading primitive data types from a stream. For example, you can use the method to read the next byte as a Boolean value and advance the current position in the stream by one byte. The class includes read methods that support different data types. When you create a new instance of the class, you provide the stream to read from, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -452,9 +452,9 @@ method passing a `true` value. + This implementation of `Close` calls the method passing a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ]]> @@ -600,7 +600,7 @@ . By default, this method specifies the `disposing` parameter as `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by `Dispose` and . By default, this method specifies the `disposing` parameter as `true`. `Finalize` specifies the `disposing` parameter as `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -672,7 +672,7 @@ for the specified encoding. + The internal buffer size is the larger value between 16 and the value returned by for the specified encoding. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -739,7 +739,7 @@ method, then set the stream back to the original position. + If surrogate characters can be expected in the stream use the method, then set the stream back to the original position. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1008,7 +1008,7 @@ :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Read/rwreadbytes.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/BinaryReader/Read/rwreadbytes.vb" id="Snippet1"::: - This example reads the contents of a file and displays each byte's numeric value in 16-column format. The end of the file that is being read is detected when the method returns zero bytes. + This example reads the contents of a file and displays each byte's numeric value in 16-column format. The end of the file that is being read is detected when the method returns zero bytes. :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source5.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source5.fs" id="Snippet6"::: @@ -1192,7 +1192,7 @@ ## Remarks does not restore the file position after an unsuccessful read. - If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . + If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1489,7 +1489,7 @@ :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/ReadBytes/rwbytes.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/BinaryReader/ReadBytes/rwbytes.vb" id="Snippet1"::: - This example reads the contents of a file and displays it to the console as dump text. The end of the file that is being read is detected when the length of the array returned from is zero. + This example reads the contents of a file and displays it to the console as dump text. The end of the file that is being read is detected when the length of the array returned from is zero. :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source5.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source5.fs" id="Snippet6"::: @@ -1560,7 +1560,7 @@ method attempts to read a surrogate character in the stream an exception will be raised and the position in the stream will advance. The position is restored to the original location before was called if the stream is seekable; however, if the stream is unseekable, the position will not be corrected. If surrogate characters can be expected in the stream, use the method instead. + If the method attempts to read a surrogate character in the stream an exception will be raised and the position in the stream will advance. The position is restored to the original location before was called if the stream is seekable; however, if the stream is unseekable, the position will not be corrected. If surrogate characters can be expected in the stream, use the method instead. Because of data formatting conflicts, using this method with the following encodings is not recommended: @@ -1657,7 +1657,7 @@ ## Remarks does not restore the file position after an unsuccessful read operation. - When reading from network streams, in some rare cases, the method might read an extra character from the stream if the was constructed with Unicode encoding. If this occurs, you can use the method to read a fixed-length byte array, and then pass that array to the method. + When reading from network streams, in some rare cases, the method might read an extra character from the stream if the was constructed with Unicode encoding. If this occurs, you can use the method to read a fixed-length byte array, and then pass that array to the method. @@ -2656,7 +2656,7 @@ allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). +Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> diff --git a/xml/System.IO/BinaryWriter.xml b/xml/System.IO/BinaryWriter.xml index fb65343d0a8..905d6efbeab 100644 --- a/xml/System.IO/BinaryWriter.xml +++ b/xml/System.IO/BinaryWriter.xml @@ -103,12 +103,12 @@ class provides methods that simplify writing primitive data types to a stream. For example, you can use the method to write a Boolean value to the stream as a one-byte value. The class includes write methods that support different data types. + The class provides methods that simplify writing primitive data types to a stream. For example, you can use the method to write a Boolean value to the stream as a one-byte value. The class includes write methods that support different data types. When you create a new instance of the class, you provide the stream to write to, and optionally specify the type of encoding and whether to leave the stream open after disposing the object. If you do not specify an encoding type, UTF-8 is used. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. A derived class can override the methods of this class to give unique character encodings. @@ -525,9 +525,9 @@ method passing a `true` value. + This implementation of `Close` calls the method passing a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ]]> @@ -763,7 +763,7 @@ ## Remarks All derived classes should override `Flush` to ensure that all buffered data is sent to the stream. - Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -957,7 +957,7 @@ ## Examples - The following example writes a series of byte values to a file. The example uses to move to various locations in the file, and then writes marker bytes by using the method. + The following example writes a series of byte values to a file. The example uses to move to various locations in the file, and then writes marker bytes by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/Overview/source3.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/BinaryReader/Overview/source3.fs" id="Snippet5"::: @@ -1343,7 +1343,7 @@ This member is an explicit interface member implementation. It can be used only For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - Unicode surrogate characters must be written out as pairs together in the same call, not individually. If you require support for surrogate pairs in your application, consider using a character array and the method overload. + Unicode surrogate characters must be written out as pairs together in the same call, not individually. If you require support for surrogate pairs in your application, consider using a character array and the method overload. @@ -1428,11 +1428,11 @@ This member is an explicit interface member implementation. It can be used only |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1519,11 +1519,11 @@ This member is an explicit interface member implementation. It can be used only |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1743,11 +1743,11 @@ This member is an explicit interface member implementation. It can be used only |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| diff --git a/xml/System.IO/BufferedStream.xml b/xml/System.IO/BufferedStream.xml index d81f02f02fc..e8788f7e350 100644 --- a/xml/System.IO/BufferedStream.xml +++ b/xml/System.IO/BufferedStream.xml @@ -83,10 +83,10 @@ and methods of `BufferedStream` automatically maintain the buffer. + A buffer is a block of bytes in memory used to cache data, thereby reducing the number of calls to the operating system. Buffers improve read and write performance. A buffer can be used for either reading or writing, but never both simultaneously. The and methods of `BufferedStream` automatically maintain the buffer. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. `BufferedStream` can be composed around certain types of streams. It provides implementations for reading and writing bytes to an underlying data source or repository. Use and for reading and writing other data types. `BufferedStream` is designed to prevent the buffer from slowing down input and output when the buffer is not needed. If you always read and write for sizes greater than the internal buffer size, then `BufferedStream` might not even allocate the internal buffer. `BufferedStream` also buffers reads and writes in a shared buffer. It is assumed that you will almost always be doing a series of reads or writes, but rarely alternate between the two of them. @@ -338,14 +338,14 @@ and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. - must be called exactly once for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. + must be called exactly once for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. > [!NOTE] > Use the property to determine whether the current instance supports reading. - must be called with this to find out how many bytes were read. + must be called with this to find out how many bytes were read. ]]> @@ -433,9 +433,9 @@ and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. - must be called exactly once on every from . will block until the I/O operation has completed. + must be called exactly once on every from . will block until the I/O operation has completed. ]]> @@ -539,7 +539,7 @@ does not support reading, calls to the , , , , and the `Peek` methods of , , and throw a . + If a class derived from does not support reading, calls to the , , , , and the `Peek` methods of , , and throw a . If the stream is closed, this property returns `false`. @@ -611,7 +611,7 @@ does not support seeking, calls to , , , and throw a . + If a class derived from does not support seeking, calls to , , , and throw a . If the stream is closed, this property returns `false`. @@ -684,7 +684,7 @@ does not support writing, a call to , , or throws a . + If a class derived from does not support writing, a call to , , or throws a . If the stream is closed, this property returns `false`. @@ -1036,9 +1036,9 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. - must be called with this to find out how many bytes were read. + must be called with this to find out how many bytes were read. ]]> @@ -1097,9 +1097,9 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , and , help you implement asynchronous file operations more easily. - must be called exactly once for every call to . Failing to end a read process before beginning another read operation can cause deadlock or other undesirable behavior. + must be called exactly once for every call to . Failing to end a read process before beginning another read operation can cause deadlock or other undesirable behavior. ]]> @@ -1158,9 +1158,9 @@ Calling `DisposeAsync` allows the resources used by the . + Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . - If you use the constructor, thus specifying the buffer size while creating the `BufferedStream` object, the content is flushed when it reaches the buffer size. For example, code such as `BufferedStream bs = new BufferedStream(bs, 5)` will flush the content when the buffer size reaches 5 bytes. + If you use the constructor, thus specifying the buffer size while creating the `BufferedStream` object, the content is flushed when it reaches the buffer size. For example, code such as `BufferedStream bs = new BufferedStream(bs, 5)` will flush the content when the buffer size reaches 5 bytes. All the read and write methods of `BufferedStream` automatically maintain the buffer, so there is no need to invoke `Flush` when switching back and forth between reading and writing. @@ -1341,9 +1341,9 @@ Calling `DisposeAsync` allows the resources used by the to obtain the current position within the underlying stream and then adjusts this value according to the current position within the buffer. + The `get` accessor invokes to obtain the current position within the underlying stream and then adjusts this value according to the current position within the buffer. - The `set` accessor copies any data previously written to the buffer to the underlying stream, and then invokes . + The `set` accessor copies any data previously written to the buffer to the underlying stream, and then invokes . Seeking to any location beyond the length of the stream is supported. @@ -1404,7 +1404,7 @@ Calling `DisposeAsync` allows the resources used by the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. The implementation will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1771,7 +1771,7 @@ If the operation is canceled before it completes, the returned task contains the ## Remarks If `offset` is negative, the new position will precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is 0, the new position will be the position specified by `origin`. If `offset` is positive, the new position will follow the position specified by `origin` by the number of bytes specified by `offset`. - When a object is the base stream for a object, calling the method can cause the position of the stream to no longer match the position of the internal buffer in the reader. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + When a object is the base stream for a object, calling the method can cause the position of the stream to no longer match the position of the internal buffer in the reader. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. Seeking to any location beyond the length of the stream is supported. @@ -1941,7 +1941,7 @@ If the operation is canceled before it completes, the returned task contains the ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current buffered stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current buffered stream. If the write operation is successful, the position within the buffered stream advances by the number of bytes written. If an exception occurs, the position within the buffered stream remains unchanged. diff --git a/xml/System.IO/Directory.xml b/xml/System.IO/Directory.xml index e80c913ad6a..bffb703ddbb 100644 --- a/xml/System.IO/Directory.xml +++ b/xml/System.IO/Directory.xml @@ -77,13 +77,13 @@ ## Remarks Use the class for typical operations such as copying, moving, renaming, creating, and deleting directories. -- To create a directory, use one of the methods. +- To create a directory, use one of the methods. -- To delete a directory, use one of the methods. +- To delete a directory, use one of the methods. -- To get or set the current directory for an app, use the or method. +- To get or set the current directory for an app, use the or method. -- To manipulate information related to the creation, access, and writing of a directory, use methods such as and . +- To manipulate information related to the creation, access, and writing of a directory, use methods such as and . The static methods of the class perform security checks on all methods. If you are going to reuse an object several times, consider using the corresponding instance method of instead, because the security check will not always be necessary. @@ -104,7 +104,7 @@ To demand permissions for a directory and all its subdirectories, end the path string with the directory separator character. (For example, "C:\Temp\\" grants access to C:\Temp\ and all its subdirectories.) To demand permissions only for a specific directory, end the path string with a period. (For example, "C:\Temp\\." grants access only to C:\Temp\\, not to its subdirectories.) - In members that accept a `searchPattern` parameter, the search string can be any combination of literal characters and two wildcard characters; \* and ?. This parameter does not recognize regular expressions. For more information, see the method or any other method that uses the `searchPattern` parameter. + In members that accept a `searchPattern` parameter, the search string can be any combination of literal characters and two wildcard characters; \* and ?. This parameter does not recognize regular expressions. For more information, see the method or any other method that uses the `searchPattern` parameter. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -119,7 +119,7 @@ :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class2.fs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Directory/Overview/class2.vb" id="Snippet10"::: - The following example demonstrates how to use the method to retrieve a collection of text files from a directory, and then use that collection in a query to find all the lines that contain "Example". + The following example demonstrates how to use the method to retrieve a collection of text files from a directory, and then use that collection in a query to find all the lines that contain "Example". :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Overview/class3.cs" id="Snippet11"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class3.fs" id="Snippet11"::: @@ -582,9 +582,9 @@ An I/O error occurred. with `false` specified for the second parameter. + This method behaves identically to with `false` specified for the second parameter. - The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Trailing spaces are removed from the end of the `path` parameter before deleting the directory. @@ -592,7 +592,7 @@ An I/O error occurred. The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. - In some cases, if you have the specified directory open in File Explorer, the method may not be able to delete it. + In some cases, if you have the specified directory open in File Explorer, the method may not be able to delete it. @@ -698,7 +698,7 @@ An I/O error occurred. . + The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Trailing spaces are removed from the end of the `path` parameter before deleting the directory. @@ -708,7 +708,7 @@ An I/O error occurred. The behavior of this method differs slightly when deleting a directory that contains a reparse point, such as a symbolic link or a mount point. If the reparse point is a directory, such as a mount point, it is unmounted and the mount point is deleted. This method does not recurse through the reparse point. If the reparse point is a symbolic link to a file, the reparse point is deleted and not the target of the symbolic link. - In some cases, if you have the specified directory open in File Explorer, the method may not be able to delete it. + In some cases, if you have the specified directory open in File Explorer, the method may not be able to delete it. @@ -814,11 +814,11 @@ An I/O error occurred. method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. + You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ## Examples The following example enumerates the top-level directories in a specified path. @@ -902,13 +902,13 @@ An I/O error occurred. Characters other than the wildcard are literal characters. For example, the `searchPattern` string "\*t" searches for all names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. + You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. @@ -999,13 +999,13 @@ An I/O error occurred. Characters other than the wildcard are literal characters. For example, the `searchPattern` string "\*t" searches for all names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. + You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ]]> @@ -1088,13 +1088,13 @@ An I/O error occurred. Characters other than the wildcard are literal characters. For example, the `searchPattern` string "\*t" searches for all names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. + You can specify relative or absolute path information in the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. The returned directory names are prefixed with the value you provided in the `path` parameter. For example, if you provide a relative path in the `path` parameter, the returned directory names will contain a relative path. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ## Examples The following example enumerates directories in a specified path that match a specified search pattern. It uses the `searchOption` parameter to specify that all subdirectories should be included in the search. @@ -1187,11 +1187,11 @@ An I/O error occurred. method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ## Examples The following example shows how to retrieve all the files in a directory and move them to a new directory. After the files are moved, they no longer exist in the original directory. @@ -1283,13 +1283,13 @@ An I/O error occurred. [!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)] - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. -The returned collection is not cached. Each call to the on the collection starts a new enumeration. +The returned collection is not cached. Each call to the on the collection starts a new enumeration. ## Examples The following example shows how to retrieve all the text files in a directory and move them to a new directory. After the files are moved, they no longer exist in the original directory. @@ -1385,13 +1385,13 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. -The returned collection is not cached. Each call to the on the collection starts a new enumeration. +The returned collection is not cached. Each call to the on the collection starts a new enumeration. ## Examples The following example shows how to retrieve all the text files in a directory and its subdirectories and move them to a new directory. After the files are moved, they no longer exist in the original directories. @@ -1492,13 +1492,13 @@ The following example recursively enumerates all files with the `.txt` extension [!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)] - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned. When you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. -The returned collection is not cached. Each call to the on the collection starts a new enumeration. +The returned collection is not cached. Each call to the on the collection starts a new enumeration. ## Examples The following example shows how to retrieve all the text files in a directory and its subdirectories, and move them to a new directory. After the files are moved, they no longer exist in the original directories. @@ -1597,11 +1597,11 @@ The returned collection is not cached. Each call to the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ]]> @@ -1686,13 +1686,13 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ]]> @@ -1782,13 +1782,13 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ]]> @@ -1883,13 +1883,13 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The returned collection is not cached; each call to the on the collection will start a new enumeration. + The returned collection is not cached; each call to the on the collection will start a new enumeration. ]]> @@ -1988,9 +1988,9 @@ The returned collection is not cached. Each call to the method will return `false`. + If you do not have at a minimum read-only permission to the directory, the method will return `false`. - The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. @@ -2055,7 +2055,7 @@ The returned collection is not cached. Each call to the method to retrieve the access control list (ACL) entries for a directory. + Use the method to retrieve the access control list (ACL) entries for a directory. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2115,7 +2115,7 @@ The returned collection is not cached. Each call to the method to retrieve the access control list (ACL) entries for a directory. + Use the method to retrieve the access control list (ACL) entries for a directory. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2199,11 +2199,11 @@ The returned collection is not cached. Each call to the [!NOTE] > This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - This method is equivalent to . + This method is equivalent to . If the directory described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -2460,11 +2460,11 @@ The returned collection is not cached. Each call to the with the asterisk (\*) specified as the search pattern, so it returns all subdirectories. If you need to search subdirectories, use the method, which enables you to specify a search of subdirectories with the `searchOption` parameter. + This method is identical to with the asterisk (\*) specified as the search pattern, so it returns all subdirectories. If you need to search subdirectories, use the method, which enables you to specify a search of subdirectories with the `searchOption` parameter. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The names returned by this method are prefixed with the directory information provided in `path`. @@ -2555,7 +2555,7 @@ The returned collection is not cached. Each call to the method and specify in the `searchOption` parameter. + This method returns all subdirectories directly under the specified directory that match the specified search pattern. If the specified directory has no subdirectories, or no subdirectories match the `searchPattern` parameter, this method returns an empty array. Only the top directory is searched. If you want to search the subdirectories as well, use the method and specify in the `searchOption` parameter. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -2566,11 +2566,11 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - The `path` parameter can specify relative or absolute path information, and is not case-sensitive. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information, and is not case-sensitive. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2655,7 +2655,7 @@ The returned collection is not cached. Each call to the method and specify in the `searchOption` parameter. + This method returns all subdirectories directly under the specified directory that match the specified search pattern. If the specified directory has no subdirectories, or no subdirectories match the `searchPattern` parameter, this method returns an empty array. Only the top directory is searched. If you want to search the subdirectories as well, use the method and specify in the `searchOption` parameter. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -2666,11 +2666,11 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - The `path` parameter can specify relative or absolute path information, and is not case-sensitive. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information, and is not case-sensitive. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2749,7 +2749,7 @@ The returned collection is not cached. Each call to the . + The `path` parameter can specify relative or absolute path information, and is not case-sensitive. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -2760,9 +2760,9 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2859,9 +2859,9 @@ The returned collection is not cached. Each call to the , and returns root directory information. The specified path is not required to exist. + This method obtains the fully qualified path name of `path`, as returned by , and returns root directory information. The specified path is not required to exist. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -2950,22 +2950,22 @@ The returned collection is not cached. Each call to the and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. The returned file names are appended to the supplied `path` parameter. - This method is identical to with the asterisk (\*) specified as the search pattern. + This method is identical to with the asterisk (\*) specified as the search pattern. - The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - The following example demonstrates how to use the method to return file names from a user-specified location. The example is configured to catch all errors common to this method. + The following example demonstrates how to use the method to return file names from a user-specified location. The example is configured to catch all errors common to this method. :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Exists/directorylisting.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Exists/directorylisting.fs" id="Snippet1"::: @@ -3044,7 +3044,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The returned file names are appended to the supplied `path` parameter and the order of the returned file names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3055,16 +3055,16 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. [!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)] > [!NOTE] > Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT". - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3148,7 +3148,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The returned file names are appended to the supplied `path` parameter and the order of the returned file names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3159,16 +3159,16 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. [!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)] > [!NOTE] > Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT". - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3249,7 +3249,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The returned file names are appended to the supplied parameter `path` and the order of the returned file names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3260,18 +3260,18 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. [!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)] > [!NOTE] > Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT". - The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of names before the whole collection is returned; when you use , you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. The file names include the full path. - The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3364,13 +3364,13 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The order of the returned file and directory names is not guaranteed; use the method if a specific sort order is required. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - This method is identical to with the asterisk (\*) specified as the search pattern. + This method is identical to with the asterisk (\*) specified as the search pattern. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3379,7 +3379,7 @@ The returned collection is not cached. Each call to the method to fill an array of strings with the names of all files and subdirectories in a user-specified location and prints each string in the array to the console. The example is configured to catch all errors common to this method. + The following example uses the method to fill an array of strings with the names of all files and subdirectories in a user-specified location and prints each string in the array to the console. The example is configured to catch all errors common to this method. :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Overview/class1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class1.fs" id="Snippet1"::: @@ -3456,7 +3456,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The order of the returned file and directory names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3467,7 +3467,7 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. > [!NOTE] > When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows: @@ -3477,7 +3477,7 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3486,7 +3486,7 @@ The returned collection is not cached. Each call to the method to fill an array of strings with the names of all files matching a user-specified filter in a specific location and prints each string in the array to the console. The example is configured to catch all errors common to this method. + The following example uses the method to fill an array of strings with the names of all files matching a user-specified filter in a specific location and prints each string in the array to the console. The example is configured to catch all errors common to this method. :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Overview/class1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class1.fs" id="Snippet2"::: @@ -3561,7 +3561,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The order of the returned file and directory names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3572,7 +3572,7 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. > [!NOTE] > When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows: @@ -3582,7 +3582,7 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3658,7 +3658,7 @@ The returned collection is not cached. Each call to the method if a specific sort order is required. + The order of the returned file and directory names is not guaranteed; use the method if a specific sort order is required. `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. @@ -3669,7 +3669,7 @@ The returned collection is not cached. Each call to the or , nor can it contain any invalid characters. You can query for invalid characters by using the method. + `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by or , nor can it contain any invalid characters. You can query for invalid characters by using the method. > [!NOTE] > When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows: @@ -3679,9 +3679,9 @@ The returned collection is not cached. Each call to the > When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files. - The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. + The and methods differ as follows: When you use , you can start enumerating the collection of entries before the whole collection is returned; when you use , you must wait for the whole array of entries to be returned before you can access the array. Therefore, when you are working with many files and directories, can be more efficient. - You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. + You can specify relative path information with the `path` parameter. Relative path information is interpreted as relative to the current working directory, which you can determine by using the method. ]]> @@ -3770,11 +3770,11 @@ The returned collection is not cached. Each call to the [!NOTE] > This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - This method is identical to . + This method is identical to . If the directory described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -3956,7 +3956,7 @@ The returned collection is not cached. Each call to the . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4132,7 +4132,7 @@ The returned collection is not cached. Each call to the method to assign the name of each drive on the calling computer to an array of strings. Each member of this string array is then printed to the console. The example is configured to catch all errors common to this method. + The following example uses the method to assign the name of each drive on the calling computer to an array of strings. Each member of this string array is then printed to the console. The example is configured to catch all errors common to this method. :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Overview/class1.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class1.fs" id="Snippet3"::: @@ -4206,11 +4206,11 @@ The returned collection is not cached. Each call to the . + The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Trailing spaces are removed from the end of the `path` parameter before getting the directory. - The string returned by this method consists of all characters in the path up to, but not including, the last or . For example, passing the path "C:\Directory\SubDirectory\test.txt" to returns "C:\Directory\SubDirectory". Passing "C:\Directory\SubDirectory" returns "C:\Directory". However, passing "C:\Directory\SubDirectory\\" returns "C:\Directory\SubDirectory", because the ending directory separator is after "SubDirectory". + The string returned by this method consists of all characters in the path up to, but not including, the last or . For example, passing the path "C:\Directory\SubDirectory\test.txt" to returns "C:\Directory\SubDirectory". Passing "C:\Directory\SubDirectory" returns "C:\Directory". However, passing "C:\Directory\SubDirectory\\" returns "C:\Directory\SubDirectory", because the ending directory separator is after "SubDirectory". The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4219,7 +4219,7 @@ The returned collection is not cached. Each call to the method to retrieve the parent directory of a user-specified location, "path". The value returned by the method is then printed to the console. The example is configured to catch all errors common to this method. + The following example demonstrates how to use the method to retrieve the parent directory of a user-specified location, "path". The value returned by the method is then printed to the console. The example is configured to catch all errors common to this method. :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/Overview/class1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class1.fs" id="Snippet4"::: @@ -4307,7 +4307,7 @@ This method creates a new directory with the name specified by `destDirName` and If you try to move a directory to a directory that already exists, an will occur. -The `sourceDirName` and `destDirName` arguments are permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . +The `sourceDirName` and `destDirName` arguments are permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Trailing spaces are removed from the end of the path parameters before moving the directory. @@ -4458,26 +4458,26 @@ There are too many levels of symbolic links. method applies access control list (ACL) entries to a directory that represents the noninherited ACL list. + The method applies access control list (ACL) entries to a directory that represents the noninherited ACL list. > [!CAUTION] -> The ACL specified for the `directorySecurity` parameter replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL and modify it. +> The ACL specified for the `directorySecurity` parameter replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL and modify it. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it's not possible to retrieve a object from one file and reapply the same object to another file. + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it's not possible to retrieve a object from one file and reapply the same object to another file. To copy ACL information from one file to another: -1. Use the method to retrieve the object from the source file. +1. Use the method to retrieve the object from the source file. 2. Create a new object for the destination file. -3. Use the or method of the source object to retrieve the ACL information. +3. Use the or method of the source object to retrieve the ACL information. -4. Use the or method to copy the information retrieved in step 3 to the destination object. +4. Use the or method to copy the information retrieved in step 3 to the destination object. -5. Set the destination object to the destination file using the method. +5. Set the destination object to the destination file using the method. In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. @@ -4547,7 +4547,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4636,7 +4636,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4718,7 +4718,7 @@ There are too many levels of symbolic links. ## Remarks When the application terminates, the working directory is restored to its original location (the directory where the process was started). - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Trailing spaces are removed from the end of the `path` parameter before setting the directory. @@ -4804,7 +4804,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4895,7 +4895,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -4980,7 +4980,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. @@ -5074,7 +5074,7 @@ There are too many levels of symbolic links. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. diff --git a/xml/System.IO/DirectoryInfo.xml b/xml/System.IO/DirectoryInfo.xml index 99534639a11..3994f1703fe 100644 --- a/xml/System.IO/DirectoryInfo.xml +++ b/xml/System.IO/DirectoryInfo.xml @@ -789,38 +789,38 @@ namespace ConsoleApp and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ## Examples The following example enumerates the subdirectories under the C:\Program Files directory and uses a LINQ query to return the names of all directories that were created before 2009 by checking the value of the property. - If you only need the names of the subdirectories, use the static class for better performance. For an example, see the method. + If you only need the names of the subdirectories, use the static class for better performance. For an example, see the method. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateDirectories/program.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateDirectories/program.fs"::: @@ -897,31 +897,31 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -986,31 +986,31 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -1087,36 +1087,36 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ## Examples - The following example uses this method and the method to enumerate the files and directories within the start directory and display the name and size of any files over 10 MB. + The following example uses this method and the method to enumerate the files and directories within the start directory and display the name and size of any files over 10 MB. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateDirectories/program1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateDirectories/program1.fs" id="Snippet1"::: @@ -1195,40 +1195,40 @@ namespace ConsoleApp and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ## Examples The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. - If you only need the names of the files, use the static class for better performance. For an example, see the method. + If you only need the names of the files, use the static class for better performance. For an example, see the method. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateFiles/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateFiles/program.fs" id="Snippet1"::: @@ -1311,33 +1311,33 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. @@ -1411,33 +1411,33 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -1514,33 +1514,33 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. @@ -1624,31 +1624,31 @@ namespace ConsoleApp and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -1722,31 +1722,31 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -1812,31 +1812,31 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -1913,31 +1913,31 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + The returned collection is not cached; each call to the method on the collection will start a new enumeration. ]]> @@ -2071,7 +2071,7 @@ namespace ConsoleApp methods to retrieve the access control list (ACL) entries for the current file. + Use methods to retrieve the access control list (ACL) entries for the current file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2112,12 +2112,12 @@ namespace ConsoleApp method overload and specifying the access control sections | | ( `Or` `Or` in Visual Basic). + Calling this method overload is equivalent to calling the method overload and specifying the access control sections | | ( `Or` `Or` in Visual Basic). An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). ## Examples - The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. + The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetAccessControl/sample.fs" id="Snippet1"::: @@ -2174,7 +2174,7 @@ namespace ConsoleApp method to retrieve the access control list (ACL) entries for the current file. + Use the method to retrieve the access control list (ACL) entries for the current file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2255,19 +2255,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -2357,19 +2357,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- ## Examples The following example counts the directories in a path that contain the specified letter. @@ -2447,19 +2447,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- ]]> @@ -2542,19 +2542,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -2644,35 +2644,35 @@ namespace ConsoleApp and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. If there are no files in the , this method returns an empty array. - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -2758,13 +2758,13 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. If there are no files in the , this method returns an empty array. @@ -2775,7 +2775,7 @@ namespace ConsoleApp |*|Zero or more characters.| |?|Exactly zero or one character.| - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. @@ -2787,21 +2787,21 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -2879,13 +2879,13 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - The and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. If there are no files in the , this method returns an empty array. @@ -2896,7 +2896,7 @@ namespace ConsoleApp |*|Zero or more characters.| |?|Exactly zero or one character.| - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. @@ -2908,21 +2908,21 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- ]]> @@ -2992,13 +2992,13 @@ namespace ConsoleApp and methods differ as follows: + The and methods differ as follows: -- When you use , you can start enumerating the collection of objects before the whole collection is returned. +- When you use , you can start enumerating the collection of objects before the whole collection is returned. -- When you use , you must wait for the whole array of objects to be returned before you can access the array. +- When you use , you must wait for the whole array of objects to be returned before you can access the array. - Therefore, when you are working with many files and directories, can be more efficient. + Therefore, when you are working with many files and directories, can be more efficient. If there are no files in the , this method returns an empty array. @@ -3009,7 +3009,7 @@ namespace ConsoleApp |\* (asterisk)|Zero or more characters.| |? (question mark)|Exactly zero or one character.| - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. @@ -3031,21 +3031,21 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -1. +1. -2. +2. -3. +3. -4. +4. -5. +5. -6. +6. -7. +7. -8. +8. @@ -3141,19 +3141,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -3251,19 +3251,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- @@ -3353,19 +3353,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- ]]> @@ -3447,19 +3447,19 @@ namespace ConsoleApp This method pre-populates the values of the following properties: -- +- -- +- -- +- -- +- -- +- -- +- -- +- ]]> @@ -3621,7 +3621,7 @@ namespace ConsoleApp ## Remarks This property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the property. - The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. + The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3841,29 +3841,29 @@ The following example refers to the parent directory of a specified directory. ## Remarks An access control list (ACL) describes individuals and groups who have, or don't have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - The method applies ACL entries to a file that represents the noninherited ACL list. + The method applies ACL entries to a file that represents the noninherited ACL list. > [!CAUTION] -> The ACL specified for `directorySecurity` replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL, and modify it. +> The ACL specified for `directorySecurity` replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL, and modify it. - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. To copy ACL information from one file to another: -1. Use the method to retrieve the object from the source file. +1. Use the method to retrieve the object from the source file. 2. Create a new object for the destination file. -3. Use the or method of the source object to retrieve the ACL information. +3. Use the or method of the source object to retrieve the ACL information. -4. Use the or method to copy the information retrieved in step 3 to the destination object. +4. Use the or method to copy the information retrieved in step 3 to the destination object. -5. Set the destination object to the destination file using the method. +5. Set the destination object to the destination file using the method. ## Examples - The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. + The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetAccessControl/sample.fs" id="Snippet1"::: @@ -3924,7 +3924,7 @@ The following example refers to the parent directory of a specified directory. ## Remarks > [!IMPORTANT] -> The string returned by the method represents the path that was passed to the constructor. Instead of calling the `ToString` method, you should retrieve the value of either of the following properties, depending on your intent: +> The string returned by the method represents the path that was passed to the constructor. Instead of calling the `ToString` method, you should retrieve the value of either of the following properties, depending on your intent: > - , to get the name of the directory, without any parent path information. > - , to get the fully qualified path of the directory. diff --git a/xml/System.IO/DirectoryNotFoundException.xml b/xml/System.IO/DirectoryNotFoundException.xml index bd7b8f028fc..f104fd5c2c6 100644 --- a/xml/System.IO/DirectoryNotFoundException.xml +++ b/xml/System.IO/DirectoryNotFoundException.xml @@ -143,7 +143,7 @@ ## Examples - The following code example demonstrates how to call the constructor. + The following code example demonstrates how to call the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryNotFoundException/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/DirectoryNotFoundException/Overview/DirectoryNotFoundexception.vb" id="Snippet1"::: @@ -327,8 +327,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.IO/DriveInfo.xml b/xml/System.IO/DriveInfo.xml index a010af481c1..75e39bd6811 100644 --- a/xml/System.IO/DriveInfo.xml +++ b/xml/System.IO/DriveInfo.xml @@ -196,7 +196,7 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o number because this property takes into account disk quotas. + This property indicates the amount of free space available on the drive. Note that this number may be different from the number because this property takes into account disk quotas. @@ -261,7 +261,7 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o to determine what formatting a drive uses. + Use to determine what formatting a drive uses. @@ -458,9 +458,9 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o indicates whether a drive is ready. For example, it indicates whether a CD is in a CD drive or whether a removable storage device is ready for read/write operations. If you do not test whether a drive is ready, and it is not ready, querying the drive using will raise an . + indicates whether a drive is ready. For example, it indicates whether a CD is in a CD drive or whether a removable storage device is ready for read/write operations. If you do not test whether a drive is ready, and it is not ready, querying the drive using will raise an . - Do not rely on to avoid catching exceptions from other members such as , , and . Between the time that your code checks and then accesses one of the other properties (even if the access occurs immediately after the check), a drive may have been disconnected or a disk may have been removed. + Do not rely on to avoid catching exceptions from other members such as , , and . Between the time that your code checks and then accesses one of the other properties (even if the access occurs immediately after the check), a drive may have been disconnected or a disk may have been removed. @@ -882,7 +882,7 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o . + The label length is determined by the operating system. For example, NTFS allows a volume label to be up to 32 characters long. Note that `null` is a valid . diff --git a/xml/System.IO/DriveNotFoundException.xml b/xml/System.IO/DriveNotFoundException.xml index 5300edd1663..62cc518e785 100644 --- a/xml/System.IO/DriveNotFoundException.xml +++ b/xml/System.IO/DriveNotFoundException.xml @@ -313,8 +313,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.IO/EndOfStreamException.xml b/xml/System.IO/EndOfStreamException.xml index d0c7f338136..fbfd4944df2 100644 --- a/xml/System.IO/EndOfStreamException.xml +++ b/xml/System.IO/EndOfStreamException.xml @@ -352,8 +352,8 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| ]]> diff --git a/xml/System.IO/ErrorEventArgs.xml b/xml/System.IO/ErrorEventArgs.xml index 5af067c86c0..8dcf93e668b 100644 --- a/xml/System.IO/ErrorEventArgs.xml +++ b/xml/System.IO/ErrorEventArgs.xml @@ -56,13 +56,13 @@ contains the that caused the event. This class provides the method to retrieve the exception. + contains the that caused the event. This class provides the method to retrieve the exception. ## Examples - The following example creates a new instance of and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. - + The following example creates a new instance of and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. + :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/source.vb" id="Snippet1"::: @@ -128,7 +128,7 @@ and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. + The following example creates a new instance of and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/.ctor/source.vb" id="Snippet1"::: @@ -182,7 +182,7 @@ and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. + The following example creates a new instance of and initializes it with an . Then the example calls to retrieve the and display the error message. There is no form associated with this code. :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/.ctor/source.vb" id="Snippet1"::: diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index f694060727e..cae86bb21c0 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -75,9 +75,9 @@ class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . + Use the class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . - Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . + Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . Because all methods are static, if you want to perform only one action, it might be more efficient to use a method than a corresponding instance method. All methods require the path to the file that you are manipulating. @@ -524,9 +524,9 @@ You can use this method to create a file that contains the following: -- The results of a [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) query on the lines of a file, as obtained by using the method. +- The results of a [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) query on the lines of a file, as obtained by using the method. -- The contents of a collection that implements an of strings. +- The contents of a collection that implements an of strings. ]]> @@ -810,7 +810,7 @@ ## Examples - The following code example demonstrates the use of the method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + The following code example demonstrates the use of the method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText.fs" id="Snippet00"::: @@ -992,7 +992,7 @@ ## Examples - The following code example demonstrates the use of the method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. + The following code example demonstrates the use of the method to add extra text to the end of a file. In this example, a file is created if it doesn't already exist, and text is added to it. However, the directory named `temp` on drive C must exist for the example to complete successfully. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText1.fs" id="Snippet00"::: @@ -1287,9 +1287,9 @@ constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. + This method is equivalent to the constructor overload. If the file specified by `path` does not exist, it is created. If the file does exist, write operations to the append text to the file. Additional threads are permitted to read the file while it is open. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . The `path` parameter is not case-sensitive. @@ -1384,20 +1384,20 @@ method overload with the `overwrite` parameter set to `false`. + This method is equivalent to the method overload with the `overwrite` parameter set to `false`. - The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. + The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. The attributes of the original file are retained in the copied file. ## Examples - The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: + The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. -- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. +- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Copy/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Copy/program.fs" id="Snippet1"::: @@ -1499,11 +1499,11 @@ ## Examples - The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: + The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Copy/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Copy/program.fs" id="Snippet1"::: @@ -1618,9 +1618,9 @@ ## Remarks The object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - This method is equivalent to the method overload using the default buffer size of 4,096 bytes. + This method is equivalent to the method overload using the default buffer size of 4,096 bytes. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are deleted and overwritten. @@ -1724,9 +1724,9 @@ ## Remarks The object created by this method has a default value of ; no other process or code can access the created file until the original file handle is closed. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. @@ -1827,9 +1827,9 @@ . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. @@ -1898,9 +1898,9 @@ . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . - This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. + This method is equivalent to the constructor overload. If the specified file does not exist, it is created; if it does exist and it is not read-only, the contents are replaced. By default, full read/write access to new files is granted to all users. The file is opened with read/write access and must be closed before it can be opened by another application. @@ -2077,9 +2077,9 @@ An I/O error occurred. constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are replaced. Additional threads are permitted to read the file while it is open. + This method is equivalent to the constructor overload with the `append` parameter set to `false`. If the file specified by `path` does not exist, it is created. If the file does exist, its contents are replaced. Additional threads are permitted to read the file while it is open. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2174,21 +2174,21 @@ An I/O error occurred. method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. + The method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. + The method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. The current file system must be formatted as NTFS and the current operating system must be Windows NT or later. ## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Decrypt/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Decrypt/sample.fs" id="Snippet1"::: @@ -2280,7 +2280,7 @@ An I/O error occurred. . + Specify a file name with any relative or absolute path information for the `path` parameter. Wildcard characters cannot be included. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . If the file to be deleted does not exist, no exception is thrown. @@ -2384,23 +2384,23 @@ An I/O error occurred. method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. + The method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. > [!IMPORTANT] > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a or , depending on the situation. > > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. - The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. + The method requires exclusive access to the file being encrypted, and will fail if another process is using the file. - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. This method is not available on all versions of Windows. For example, it is not available on Home editions. The current file system must be formatted as NTFS. ## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. + The following code example uses the method and the method to encrypt and then decrypt a file. The file must exist for the example to work. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Decrypt/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Decrypt/sample.fs" id="Snippet1"::: @@ -2503,17 +2503,17 @@ An I/O error occurred. ## Remarks -Don't use the method for path validation; this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . +Don't use the method for path validation; this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . - To check if a directory exists, see . + To check if a directory exists, see . - Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . + Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . If `path` describes a directory, this method returns `false`. Trailing spaces are removed from the `path` parameter before determining if the file exists. - The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + The method returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. ## Examples The following example determines if a file exists. @@ -2577,7 +2577,7 @@ Don't use the method for path validation; this m method to retrieve the access control list (ACL) entries for a file. + Use the method to retrieve the access control list (ACL) entries for a file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2641,7 +2641,7 @@ Don't use the method for path validation; this m method to retrieve the access control list (ACL) entries for a file. + Use the method to retrieve the access control list (ACL) entries for a file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -2766,7 +2766,7 @@ Don't use the method for path validation; this m . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2899,7 +2899,7 @@ Don't use the method for path validation; this m > [!NOTE] > This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. @@ -3041,7 +3041,7 @@ Don't use the method for path validation; this m ## Examples - The following example demonstrates the method. + The following example demonstrates the method. :::code language="vb" source="~/snippets/visualbasic/System.IO/File/GetCreationTime/module2.vb" id="Snippet2"::: @@ -3165,7 +3165,7 @@ Don't use the method for path validation; this m If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3298,7 +3298,7 @@ Don't use the method for path validation; this m If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3422,7 +3422,7 @@ Don't use the method for path validation; this m If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3555,7 +3555,7 @@ Don't use the method for path validation; this m If the file described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3741,7 +3741,7 @@ Note that if you attempt to replace a file by moving a file of the same name int - In all .NET versions, you can call before calling `Move`, which will only delete the file if it exists. -The `sourceFileName` and `destFileName` arguments can include relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . +The `sourceFileName` and `destFileName` arguments can include relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Moving the file across disk volumes is equivalent to copying the file and deleting it from the source if the copying was successful. @@ -3832,7 +3832,7 @@ The following example moves a file. This method works across disk volumes, and it does not throw an exception if the source and destination are the same. -The `sourceFileName` and `destFileName` arguments can include relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . +The `sourceFileName` and `destFileName` arguments can include relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Moving the file across disk volumes is equivalent to copying the file and deleting it from the source if the copying was successful. @@ -3946,7 +3946,7 @@ The following example moves a file. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4106,7 +4106,7 @@ The following example moves a file. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . @@ -4217,7 +4217,7 @@ The following example moves a file. . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4420,9 +4420,9 @@ The following example moves a file. constructor overload with a value of , a value of and a value of . + This method is equivalent to the constructor overload with a value of , a value of and a value of . - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4516,9 +4516,9 @@ The following example moves a file. constructor overload. + This method is equivalent to the constructor overload. - The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4606,13 +4606,13 @@ The following example moves a file. constructor overload with file mode set to , the access set to , and the share mode set to . + This method is equivalent to the constructor overload with file mode set to , the access set to , and the share mode set to . - The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). + The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (such as "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). - The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. + The `path` parameter may specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, use the method. - The returned does not support reading. To open a file for both reading and writing, use . + The returned does not support reading. To open a file for both reading and writing, use . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4851,7 +4851,7 @@ The following example moves a file. ## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadAllLines/AllText.fs" id="Snippet00"::: @@ -4950,7 +4950,7 @@ The following example moves a file. ## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText_Encoding.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadAllLines/AllText_Encoding.fs" id="Snippet00"::: @@ -5148,14 +5148,14 @@ The following example moves a file. This method attempts to automatically detect the encoding of a file based on the presence of byte order marks. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. - Use the method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. + Use the method overload when reading files that might contain imported text, because unrecognized characters may not be read correctly. The file handle is guaranteed to be closed by this method, even if exceptions are raised. ## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText.fs" id="Snippet00"::: @@ -5258,7 +5258,7 @@ The following example moves a file. ## Examples - The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to display the contents of a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText1.fs" id="Snippet00"::: @@ -5450,20 +5450,15 @@ The following example moves a file. and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. +The and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned; when you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - You can use the method to do the following: +You can use the method to do the following: - Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . - - This method uses for the encoding value. - - +This method uses for the encoding value. ## Examples The following example reads the lines of a file to find lines that contain specified strings. @@ -5472,7 +5467,7 @@ The following example moves a file. :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadLines/program.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/File/ReadLines/program.vb" id="Snippet1"::: - The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". + The following example uses the method in a LINQ query that enumerates all directories for files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft". :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/EnumerateFiles/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/EnumerateFiles/program.fs" id="Snippet1"::: @@ -5563,18 +5558,15 @@ The following example moves a file. and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. +The and methods differ as follows: When you use , you can start enumerating the collection of strings before the whole collection is returned. When you use , you must wait for the whole array of strings be returned before you can access the array. Therefore, when you are working with very large files, can be more efficient. - You can use the method to do the following: +You can use the method to do the following: - Perform [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) queries on a file to obtain a filtered set of its lines. - -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - -- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. +- Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . ]]> @@ -5698,7 +5690,7 @@ The following example moves a file. methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. + The methods replace the contents of a specified file with the contents of another file. They also create a backup of the file that was replaced. ]]> @@ -5764,7 +5756,7 @@ The following example moves a file. method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + The method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. If the `sourceFileName` and `destinationFileName` are on different volumes, this method raises an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. @@ -5773,7 +5765,7 @@ The following example moves a file. If the `destinationBackupFileName` already exists, it's replaced with the contents of the `destinationFileName` file. ## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. + The following code example uses the method to replace a file with another file and create a backup of the replaced file. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Replace/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Replace/sample.fs" id="Snippet1"::: @@ -5879,7 +5871,7 @@ The caller does not have the required permission. method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. + The method replaces the contents of a specified file with the contents of another file. It also creates a backup of the file that was replaced. If the `sourceFileName` and `destinationFileName` are on different volumes, this method raises an exception. If the `destinationBackupFileName` is on a different volume from the source file, the backup file will be deleted. @@ -5888,7 +5880,7 @@ The caller does not have the required permission. If the `destinationBackupFileName` already exists, it's replaced with the contents of the `destinationFileName` file. ## Examples - The following code example uses the method to replace a file with another file and create a backup of the replaced file. + The following code example uses the method to replace a file with another file and create a backup of the replaced file. :::code language="csharp" source="~/snippets/csharp/System.IO/File/Replace/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/Replace/sample.fs" id="Snippet1"::: @@ -6033,26 +6025,26 @@ There are too many levels of symbolic links. method applies access control list (ACL) entries to a file that represents the noninherited ACL list. + The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it's not possible to retrieve a object from one file and reapply the same object to another file. + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it's not possible to retrieve a object from one file and reapply the same object to another file. To copy ACL information from one file to another: -1. Use the method to retrieve the object from the source file. +1. Use the method to retrieve the object from the source file. 2. Create a new object for the destination file. -3. Use the or method of the source object to retrieve the ACL information. +3. Use the or method of the source object to retrieve the ACL information. -4. Use the or method to copy the information retrieved in step 3 to the destination object. +4. Use the or method to copy the information retrieved in step 3 to the destination object. -5. Set the destination object to the destination file using the method. +5. Set the destination object to the destination file using the method. In NTFS environments, and are granted to the user if the user has rights on the parent folder. To deny and , deny on the parent directory. @@ -6188,11 +6180,11 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . Certain file attributes, such as and , can be combined. Other attributes, such as , must be used alone. - It is not possible to change the compression status of a object using the method. + It is not possible to change the compression status of a object using the method. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -6332,7 +6324,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. @@ -6461,7 +6453,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. @@ -6585,7 +6577,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -6721,7 +6713,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -6842,7 +6834,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -6978,7 +6970,7 @@ It is not possible to change the compression status of a o . + The `path` parameter is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -7422,14 +7414,11 @@ It is not possible to change the compression status of a o method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - If the target file already exists, it is truncated and overwritten. - - You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. +The default behavior of the method is to write out data by using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. +If the target file already exists, it is truncated and overwritten. +You can use this method to create the contents for a collection class that takes an in its constructor, such as a , , or a class. ## Examples The following example writes selected lines from a sample data file to a file. @@ -7525,17 +7514,14 @@ It is not possible to change the compression status of a o method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. - - Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. +If the target file already exists, it is truncated and overwritten. +The default behavior of the method is to write out data using UTF-8 encoding without a byte order mark (BOM). If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. +Given a string array and a file path, this method opens the specified file, writes the string array to the file, and then closes the file. ## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadAllLines/AllText.fs" id="Snippet00"::: @@ -7634,9 +7620,9 @@ It is not possible to change the compression status of a o You can use this method to create a file that contains the following: -- The results of a [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) query on the lines of a file, as obtained by using the method. +- The results of a [LINQ to Objects](/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) query on the lines of a file, as obtained by using the method. -- The contents of a collection that implements an of strings. +- The contents of a collection that implements an of strings. ]]> @@ -7735,7 +7721,7 @@ It is not possible to change the compression status of a o ## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/ReadAllLines/AllText_Encoding.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/ReadAllLines/AllText_Encoding.fs" id="Snippet00"::: @@ -8014,14 +8000,14 @@ It is not possible to change the compression status of a o method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. + This method uses UTF-8 encoding without a Byte-Order Mark (BOM), so using the method will return an empty byte array. If it is necessary to include a UTF-8 identifier, such as a byte order mark, at the beginning of a file, use the method overload with encoding. Given a string and a file path, this method opens the specified file, writes the string to the file, and then closes the file. ## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText.fs" id="Snippet00"::: @@ -8204,7 +8190,7 @@ It is not possible to change the compression status of a o ## Examples - The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. + The following code example demonstrates the use of the method to write text to a file. In this example a file is created, if it doesn't already exist, and text is added to it. :::code language="csharp" source="~/snippets/csharp/System.IO/File/AppendAllText/AllText1.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/File/AppendAllText/AllText1.fs" id="Snippet00"::: diff --git a/xml/System.IO/FileAttributes.xml b/xml/System.IO/FileAttributes.xml index 226a9b6b4fc..b07782b2b9e 100644 --- a/xml/System.IO/FileAttributes.xml +++ b/xml/System.IO/FileAttributes.xml @@ -75,13 +75,13 @@ Provides attributes for files and directories. - method, and you can set them by calling the method. - - It is not possible to change the compression status of a object by using the method. Instead, you must actually compress the file using either a compression tool or one of the classes in the namespace. - + method, and you can set them by calling the method. + + It is not possible to change the compression status of a object by using the method. Instead, you must actually compress the file using either a compression tool or one of the classes in the namespace. + The following attributes are not supported by .NET Core on Linux and macOS: - @@ -96,14 +96,14 @@ The following attributes are not supported by .NET Core on Linux and macOS: - - -On Unix systems, the value returned by includes `Hidden` for a file whose name begins with a period ("."). On macOS, you can get or set the hidden flag. +On Unix systems, the value returned by includes `Hidden` for a file whose name begins with a period ("."). On macOS, you can get or set the hidden flag. + +## Examples + The following example shows how to retrieve the attributes for a file and check if the file is read-only. -## Examples - The following example shows how to retrieve the attributes for a file and check if the file is read-only. - :::code language="csharp" source="~/snippets/csharp/System.IO/FileAttributes/Overview/example.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileAttributes/Overview/example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/FileAttributes/Overview/example.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System.IO/FileAttributes/Overview/example.vb" id="Snippet1"::: ]]> diff --git a/xml/System.IO/FileFormatException.xml b/xml/System.IO/FileFormatException.xml index 64c410c1d2b..65ee86d1080 100644 --- a/xml/System.IO/FileFormatException.xml +++ b/xml/System.IO/FileFormatException.xml @@ -551,7 +551,7 @@ returns an empty string. + If there was an error in obtaining the name the file that caused the exception, the return value is `null`, and SourceUri. returns an empty string. ]]> diff --git a/xml/System.IO/FileInfo.xml b/xml/System.IO/FileInfo.xml index 9e3907e8922..7dfdbdb018e 100644 --- a/xml/System.IO/FileInfo.xml +++ b/xml/System.IO/FileInfo.xml @@ -80,7 +80,7 @@ If you are performing multiple operations on the same file, it can be more efficient to use instance methods instead of the corresponding static methods of the class, because a security check will not always be necessary. - Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , , , or . + Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , , , or . By default, full read/write access to new files is granted to all users. @@ -115,16 +115,16 @@ - The property retrieves or sets a value that specifies whether a file can be modified. -- The retrieves the size of a file. +- The retrieves the size of a file. -- The retrieves the name of a file. +- The retrieves the name of a file. ## Examples The following example demonstrates some of the main members of the `FileInfo` class. - When the properties are first retrieved, calls the method and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + When the properties are first retrieved, calls the method and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Overview/finfo class.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Overview/finfo class.vb" id="Snippet1"::: @@ -551,7 +551,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. ## Remarks By default, full read/write access to new files is granted to all users. - This method is a wrapper for the functionality provided by . + This method is a wrapper for the functionality provided by . @@ -736,16 +736,16 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. + The method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. ## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. + The following code example uses the method and the method to encrypt and then decrypt a file. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Decrypt/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Decrypt/sample.vb" id="Snippet1"::: @@ -990,7 +990,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. ## Remarks To get the parent directory as a object, use the property. - When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. ## Examples The following example retrieves the full path of the specified file. @@ -1063,16 +1063,16 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. + The method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. ## Examples - The following code example uses the method and the method to encrypt a file and then decrypt it. + The following code example uses the method and the method to encrypt a file and then decrypt it. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Decrypt/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Decrypt/sample.vb" id="Snippet1"::: @@ -1150,7 +1150,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. @@ -1213,12 +1213,12 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. method to retrieve the access control list (ACL) entries for the current file. + Use the method to retrieve the access control list (ACL) entries for the current file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). ## Examples - The following code example uses the method and the method to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + The following code example uses the method and the method to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/GetAccessControl/sample.vb" id="Snippet1"::: @@ -1271,7 +1271,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. method to retrieve the access control list (ACL) entries for the current file. + Use the method to retrieve the access control list (ACL) entries for the current file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -1349,7 +1349,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. If the current file does not exist, getting this property will always return `true`, but attempts to set will throw a . - When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. @@ -1427,19 +1427,19 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. ## Remarks The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. @@ -1673,7 +1673,7 @@ The following example demonstrates moving a file to a different location and ren calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. The name of the file includes the file extension. @@ -2194,7 +2194,7 @@ The following example demonstrates moving a file to a different location and ren method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (like "Second run"), the file will contain a mix of the strings ("Second run test of the OpenWrite method."). + The method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (like "Second run"), the file will contain a mix of the strings ("Second run test of the OpenWrite method."). @@ -2222,7 +2222,7 @@ The following example demonstrates moving a file to a different location and ren methods when you need to quickly replace a file with the contents of the file described by the current object. + Use the methods when you need to quickly replace a file with the contents of the file described by the current object. ]]> @@ -2297,12 +2297,12 @@ The following example demonstrates moving a file to a different location and ren method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. + The method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. ## Examples - The following example uses the method to replace a file with another file and create a backup of the replaced file. + The following example uses the method to replace a file with another file and create a backup of the replaced file. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Replace/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Replace/sample.vb" id="Snippet1"::: @@ -2395,12 +2395,12 @@ The following example demonstrates moving a file to a different location and ren method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. + The method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. Pass `null` to the `destinationBackupFileName` parameter if you do not want to create a backup of the file being replaced. ## Examples - The following example uses the method to replace a file with another file and create a backup of the replaced file. + The following example uses the method to replace a file with another file and create a backup of the replaced file. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Replace/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Replace/sample.vb" id="Snippet1"::: @@ -2462,31 +2462,31 @@ The following example demonstrates moving a file to a different location and ren method applies access control list (ACL) entries to the current file that represents the noninherited ACL list. + The method applies access control list (ACL) entries to the current file that represents the noninherited ACL list. - Use the method whenever you need to add or remove ACL entries from a file. + Use the method whenever you need to add or remove ACL entries from a file. > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. To copy ACL information from one file to another: -1. Use the method to retrieve the object from the source file. +1. Use the method to retrieve the object from the source file. 2. Create a new object for the destination file. -3. Use the or method of the source object to retrieve the ACL information. +3. Use the or method of the source object to retrieve the ACL information. -4. Use the or method to copy the information retrieved in step 3 to the destination object. +4. Use the or method to copy the information retrieved in step 3 to the destination object. -5. Set the destination object to the destination file using the method. +5. Set the destination object to the destination file using the method. ## Examples - The following code example uses the method and the method to add and then remove an ACL entry from a file. You must supply a valid user or group account to run this example. + The following code example uses the method and the method to add and then remove an ACL entry from a file. You must supply a valid user or group account to run this example. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/GetAccessControl/sample.vb" id="Snippet1"::: @@ -2544,7 +2544,7 @@ The following example demonstrates moving a file to a different location and ren ## Remarks > [!IMPORTANT] -> The string returned by the method represents the path that was passed to the constructor. Instead of calling the `ToString` method, you should retrieve the value of either of the following properties, depending on your intent: +> The string returned by the method represents the path that was passed to the constructor. Instead of calling the `ToString` method, you should retrieve the value of either of the following properties, depending on your intent: > - , to get the name of the file, without any parent path information. > - [FullName](xref:System.IO.FileSystemInfo.FullName), to get the fully qualified path of the file. diff --git a/xml/System.IO/FileLoadException.xml b/xml/System.IO/FileLoadException.xml index 14a27b3433c..4f3e5bc0d2a 100644 --- a/xml/System.IO/FileLoadException.xml +++ b/xml/System.IO/FileLoadException.xml @@ -84,13 +84,13 @@ The exact timing of when static assembly references are loaded is unspecified. T This exception is thrown if the file is not a valid .NET assembly. For more information, see . **Check to make sure an assembly or module was not loaded twice with two different evidences.** - Evidence is the set of information that constitutes input to security policy decisions, such as what permissions can be granted to code. For more information, see and + Evidence is the set of information that constitutes input to security policy decisions, such as what permissions can be granted to code. For more information, see and - **If using the or methods, check to make sure the assembly name is not longer than the system-defined maximum length.** + **If using the or methods, check to make sure the assembly name is not longer than the system-defined maximum length.** The assembly name's length cannot exceed the system-defined maximum. For more information, see . **If loading a satellite assembly, make sure the specified CultureInfo matches the file's CultureInfo.** - Satellite assemblies contain localized resources which contain non-localizable executable code and resources for a single culture that serve as the default or neutral culture. For more information, see . + Satellite assemblies contain localized resources which contain non-localizable executable code and resources for a single culture that serve as the default or neutral culture. For more information, see . ]]> @@ -332,10 +332,10 @@ The exact timing of when static assembly references are loaded is unspecified. T |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> @@ -396,7 +396,7 @@ The exact timing of when static assembly references are loaded is unspecified. T ## Remarks This constructor initializes the property of the new instance using `message` and the property using `fileName`. The property of the new instance is initialized to `null`. - is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. + is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. ]]> @@ -457,16 +457,16 @@ The exact timing of when static assembly references are loaded is unspecified. T ## Remarks An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. - is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. + is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. The following table shows the initial property values for an instance of . |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> @@ -704,9 +704,9 @@ The exact timing of when static assembly references are loaded is unspecified. T . + This property overrides . - If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. + If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. This property is read-only. @@ -769,9 +769,9 @@ The exact timing of when static assembly references are loaded is unspecified. T . + This method overrides . - The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. ]]> diff --git a/xml/System.IO/FileNotFoundException.xml b/xml/System.IO/FileNotFoundException.xml index 835db1ca4e0..fbb6dcd0b3b 100644 --- a/xml/System.IO/FileNotFoundException.xml +++ b/xml/System.IO/FileNotFoundException.xml @@ -340,10 +340,10 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> @@ -475,10 +475,10 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> @@ -793,9 +793,9 @@ . + This method overrides . - The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. ]]> diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index b8ddf6d3f51..cd9ce7deaf8 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -160,9 +160,9 @@ is called, the handle is also closed and the file's handle count is decremented. + When is called, the handle is also closed and the file's handle count is decremented. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -257,9 +257,9 @@ is called, the handle is also closed and the file's handle count is decremented. + When is called, the handle is also closed and the file's handle count is decremented. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -354,7 +354,7 @@ > [!NOTE] > `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -538,7 +538,7 @@ The file was too large (when before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -640,9 +640,9 @@ The file was too large (when method will also close the handle and the file's handle count is decremented. The `FileStream` object is given the default buffer size of 4096 bytes. + The `FileStream` object is given the specified access to the file. The ownership of the handle will be as specified. If this process owns the handle, a call to the method will also close the handle and the file's handle count is decremented. The `FileStream` object is given the default buffer size of 4096 bytes. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling methods other than `Close` after you are done using the handle. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling methods other than `Close` after you are done using the handle. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -735,7 +735,7 @@ The file was too large (when , , or method. When the `isAsync` parameter is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. + You set the `isAsync` parameter to `true` to open the file handle asynchronously. When the parameter is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the parameter does not have to be `true` to call the , , or method. When the `isAsync` parameter is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -938,9 +938,9 @@ The file was too large (when method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. + The `FileStream` object is given the specified access to the file. The ownership of the handle will be as specified. If this `FileStream` owns the handle, a call to the method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -1035,7 +1035,7 @@ The file was too large (when method. + This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet2"::: @@ -1155,9 +1155,9 @@ The file was too large (when method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. + The `FileStream` object is given the specified access to the file. The ownership of the handle will be as specified. If this `FileStream` owns the handle, a call to the method will also close the handle. In particular, the file's handle count is decremented. The `FileStream` object is given the specified buffer size. - `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. + `FileStream` assumes that it has exclusive control over the handle. Reading, writing, or seeking while a `FileStream` is also holding a handle could result in data corruption. For data safety, call before using the handle, and avoid calling any methods other than `Close` after you are done using the handle. Alternately, read and write to the handle before calling this `FileStream` constructor. `FileShare.Read` is the default for those constructors without a `FileShare` parameter. @@ -1253,7 +1253,7 @@ The file was too large (when [!NOTE] > `path` is not required to be a file stored on disk; it can be any part of a system that supports access through streams. For example, depending on the system, this class can access a physical device. - is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . + is `true` for all objects that encapsulate files. If `path` indicates a device that does not support seeking, the property on the resulting is `false`. For additional information, see . > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -1486,7 +1486,7 @@ The file was too large (when constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. + Use this constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. The `fileOptions` parameter is used to provide access to more advanced operations that you can use when creating a object. @@ -1596,7 +1596,7 @@ The file was too large (when constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. + Use this constructor to apply access rights at the point of creation of a file. To access or modify rights on an existing file, consider using the and methods. The `fileOptions` parameter is used to provide access to more advanced operations that you can use when creating a object. @@ -1702,7 +1702,7 @@ The file was too large (when does not support reading, calls to the , , and methods throw a . + If a class derived from does not support reading, calls to the , , and methods throw a . If the stream is closed, this property returns `false`. @@ -2085,7 +2085,7 @@ The file was too large (when does not support seeking, calls to , , , and throw a . + If a class derived from does not support seeking, calls to , , , and throw a . If the stream is closed, this property returns `false`. @@ -2154,7 +2154,7 @@ The file was too large (when does not support writing, a call to , , , or throws a . + If a class derived from does not support writing, a call to , , , or throws a . If the stream is closed, this property returns `false`. @@ -2310,7 +2310,7 @@ If the operation is canceled before it completes, the returned task contains the Copying begins at the current position in the current file stream. -For an example of copying between two streams, see the overload. +For an example of copying between two streams, see the overload. ]]> @@ -2381,7 +2381,7 @@ For an example of copying between two streams, see the method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. @@ -2506,18 +2506,18 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. - must be called exactly for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. + must be called exactly for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. - This method overrides . + This method overrides . - can be called on every from . Calling tells you how many bytes were read from the stream. will block until the I/O operation has completed. + can be called on every from . Calling tells you how many bytes were read from the stream. will block until the I/O operation has completed. ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet4"::: @@ -2592,16 +2592,16 @@ Calling `DisposeAsync` allows the resources used by the and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous file operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous file operations more easily. - This method overrides . + This method overrides . - must be called exactly once on every from . will block until the I/O operation has completed. + must be called exactly once on every from . will block until the I/O operation has completed. ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet3"::: @@ -2747,24 +2747,24 @@ Calling `DisposeAsync` allows the resources used by the . + This method overrides . - When you call the method, the operating system I/O buffer is also flushed. + When you call the method, the operating system I/O buffer is also flushed. - A stream's encoder is not flushed unless you explicitly call or dispose of the object. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + A stream's encoder is not flushed unless you explicitly call or dispose of the object. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. Because a buffer can be used for either reading or writing, performs the following two functions: - Any data previously written to the buffer is copied to the file and the buffer is cleared except for its encoder state. -- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. +- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. - Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. + Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. ## Examples - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet4"::: @@ -2836,7 +2836,7 @@ Calling `DisposeAsync` allows the resources used by the method, the operating system I/O buffer is also flushed. + When you call the method, the operating system I/O buffer is also flushed. ]]> @@ -2956,9 +2956,9 @@ This method flushes the .NET stream buffers to the file, but does not flush inte class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it's easier to use. + While the class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it's easier to use. - Use the method to retrieve the ACL entries for a file. + Use the method to retrieve the ACL entries for a file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -3104,12 +3104,12 @@ This method flushes the .NET stream buffers to the file, but does not flush inte ## Remarks The `IsAsync` property detects whether the `FileStream` handle was opened asynchronously, enabling your code to use the property correctly. In Win32, `IsAsync` being true means the handle was opened for overlapped I/O, and thus requires different parameters to `ReadFile` and `WriteFile`. - You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. + You specify this value when you create an instance of the class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the property does not have to be `true` to call the , , or method. When the property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously. ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet2"::: @@ -3359,7 +3359,7 @@ If the absolute path is not known, this property returns a string similar to "[U ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/source1.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source1.fs" id="Snippet4"::: @@ -3497,7 +3497,7 @@ If the absolute path is not known, this property returns a string similar to "[U ## Remarks -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method reads a maximum of `buffer.Length` bytes from the current file stream and stores them in `buffer`. The current position within the file stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the file stream remains unchanged. The method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the file stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the file stream has not been reached. @@ -3577,11 +3577,11 @@ Use for reading primitive data types. . + This method overrides . The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin reading, and the `count` parameter gives the maximum number of bytes to be read from this stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. - The method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + The method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. Use for reading primitive data types. @@ -3831,10 +3831,10 @@ The following example shows how to read from a file asynchronously. . + This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports reading. For additional information, see . +> Use the property to determine whether the current instance supports reading. For additional information, see . @@ -3912,7 +3912,7 @@ The following example shows how to read from a file asynchronously. property automatically flushes the stream and sets the current stream position to 0. This allows the file to be moved or the stream position to be reset by another stream using the returned by this property. + The property automatically flushes the stream and sets the current stream position to 0. This allows the file to be moved or the stream position to be reset by another stream using the returned by this property. ]]> @@ -3981,10 +3981,10 @@ The following example shows how to read from a file asynchronously. . + This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports seeking. For additional information, see . +> Use the property to determine whether the current instance supports seeking. For additional information, see . You can seek to any location beyond the length of the stream. When you seek beyond the length of the file, the file size grows. Data added to the end of the file is set to zero. @@ -3997,7 +3997,7 @@ The following example shows how to read from a file asynchronously. :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/source.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileStream/.ctor/source.vb" id="Snippet1"::: - The following example reads text in the reverse direction, from the end of file to the beginning of the file, by using the various values with the method. + The following example reads text in the reverse direction, from the end of file to the beginning of the file, by using the various values with the method. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Seek/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/Seek/source.fs" id="Snippet1"::: @@ -4055,12 +4055,12 @@ The following example shows how to read from a file asynchronously. class and can be used on an existing file, consider using the method as it's easier to use. + While the class and can be used on an existing file, consider using the method as it's easier to use. - The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. + The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. An ACL describes individuals and groups who have, or don't have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). @@ -4129,14 +4129,14 @@ The following example shows how to read from a file asynchronously. . + This method overrides . If the given value is less than the current length of the stream, the stream is truncated. In this scenario, if the current position is greater than the new length, the current position is moved to the last byte of the stream. If the given value is larger than the current length of the stream, the stream is expanded, and the current position remains the same. If the stream is expanded, the contents of the stream between the old and the new length are undefined on Windows, while on Linux, that space is filled with zeros. A stream must support both writing and seeking for `SetLength` to work. > [!NOTE] -> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . +> Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. For additional information, see and . For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4287,7 +4287,7 @@ The following example shows how to read from a file asynchronously. ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the file stream advances by the number of bytes written. If an exception occurs, the position within the file stream remains unchanged. @@ -4365,19 +4365,19 @@ If the write operation is successful, the position within the file stream advanc ## Remarks -This method overrides . +This method overrides . The `offset` parameter gives the offset of the byte in `array` (the buffer index) at which to begin copying, and the `count` parameter gives the number of bytes that will be written to the stream. If the write operation is successful, the current position of the stream is advanced by the number of bytes written. If an exception occurs, the current position of the stream is unchanged. > [!NOTE] -> Use the property to determine whether the current instance supports writing. For additional information, see . +> Use the property to determine whether the current instance supports writing. For additional information, see . Do not interrupt a thread that's performing a write operation. Although the application may appear to run successfully after the thread is unblocked, the interruption can decrease your application's performance and reliability. For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/FileStream/.ctor/fstreamlock.fs" id="Snippet3"::: @@ -4530,7 +4530,7 @@ If the operation is canceled before it completes, the returned task contains the method enables you to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in apps where a time-consuming stream operation can block the UI thread and make your app appear as if it isn't working. + The method enables you to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in apps where a time-consuming stream operation can block the UI thread and make your app appear as if it isn't working. Use the property to determine whether the current instance supports writing. @@ -4615,12 +4615,12 @@ This method stores in the task it returns all non-usage exceptions that the meth . + This method overrides . Use `WriteByte` to write a byte to a `FileStream` efficiently. If the stream is closed or not writable, an exception will be thrown. > [!NOTE] -> Use the property to determine whether the current instance supports writing. For additional information, see . +> Use the property to determine whether the current instance supports writing. For additional information, see . ## Examples The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly. diff --git a/xml/System.IO/FileSystemEventArgs.xml b/xml/System.IO/FileSystemEventArgs.xml index 6ea5c7c05ef..4b400ee8f33 100644 --- a/xml/System.IO/FileSystemEventArgs.xml +++ b/xml/System.IO/FileSystemEventArgs.xml @@ -59,11 +59,11 @@ The class is passed as a parameter to event handlers for these events: -- The event occurs when changes are made to the size, system attributes, last write time, last access time, or security permissions in a file or directory in the specified of a . +- The event occurs when changes are made to the size, system attributes, last write time, last access time, or security permissions in a file or directory in the specified of a . -- The event occurs when a file or directory in the specified of a is created. +- The event occurs when a file or directory in the specified of a is created. -- The event occurs when a file or directory in the specified of a is deleted. For more information, see . +- The event occurs when a file or directory in the specified of a is deleted. For more information, see . ## Examples The following example shows how to create a to monitor file changes (creates, deletes, renames, changes) occurring on a disk drive. The example also shows how to properly receive error notifications. diff --git a/xml/System.IO/FileSystemInfo.xml b/xml/System.IO/FileSystemInfo.xml index 4a7cd09b2a5..23e108797e7 100644 --- a/xml/System.IO/FileSystemInfo.xml +++ b/xml/System.IO/FileSystemInfo.xml @@ -314,19 +314,19 @@ ## Remarks The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - The value may be cached when either the value itself or other properties are accessed. To get the latest value, call the method. + The value may be cached when either the value itself or other properties are accessed. To get the latest value, call the method. If the path doesn't exist as of the last cached state, the return value is `(FileAttributes)(-1)`. or can only be thrown when setting the value. @@ -477,19 +477,19 @@ An I/O error occurred. The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. @@ -580,19 +580,19 @@ On Unix platforms that do not support creation or birth time, this property retu The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). @@ -788,10 +788,10 @@ The `Extension` property returns the extension, |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Retrieve the fully qualified path of a file.|| -|Retrieve only the file name a path.|| -|Retrieve only the directory name from a path.|| -|Change the extension of a file.|| +|Retrieve the fully qualified path of a file.|| +|Retrieve only the file name a path.|| +|Retrieve only the directory name from a path.|| +|Change the extension of a file.|| ]]> @@ -1077,24 +1077,24 @@ The `Extension` property returns the extension, The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. ## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/LastAccessTime/touch.vb" id="Snippet00"::: @@ -1175,19 +1175,19 @@ The `Extension` property returns the extension, The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). @@ -1265,24 +1265,24 @@ The `Extension` property returns the extension, The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. ## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/LastAccessTime/touch.vb" id="Snippet00"::: @@ -1363,19 +1363,19 @@ The `Extension` property returns the extension, The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: -- +- -- +- -- +- -- +- -- +- -- +- - To get the latest value, call the method. + To get the latest value, call the method. If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). diff --git a/xml/System.IO/FileSystemWatcher.xml b/xml/System.IO/FileSystemWatcher.xml index 6e60068bd5b..7870e47c81d 100644 --- a/xml/System.IO/FileSystemWatcher.xml +++ b/xml/System.IO/FileSystemWatcher.xml @@ -153,15 +153,15 @@ |Property|Initial Value| |--------------|-------------------| -||bitwise OR combination of `LastWrite`, `FileName`, and `DirectoryName`| -||`false`| -||"*.\*" (Watch all files.)| -||`false`| -||8192| -||empty string ("")| +||bitwise OR combination of `LastWrite`, `FileName`, and `DirectoryName`| +||`false`| +||"*.\*" (Watch all files.)| +||`false`| +||8192| +||empty string ("")| > [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. +> The component will not watch the specified directory until the is set, and is `true`. @@ -238,7 +238,7 @@ ## Remarks > [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. +> The component will not watch the specified directory until the is set, and is `true`. The component can watch files on your personal computer, a network drive, or a remote computer. @@ -314,7 +314,7 @@ ## Remarks > [!NOTE] -> The component will not watch the specified directory until the is set, and is `true`. +> The component will not watch the specified directory until the is set, and is `true`. The component can watch files on your personal computer, a network drive, or a remote computer. @@ -392,7 +392,7 @@ method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to start the initialization of a component used on a form or used by another component. The method ends the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -452,9 +452,9 @@ The event is raised when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . - Use to restrict the number of notifications raised when this event is handled. + Use to restrict the number of notifications raised when this event is handled. > [!NOTE] > The event is raised unexpectedly when a file is renamed, but is not raised when a directory is renamed. To watch for renaming, use the event. @@ -532,12 +532,12 @@ Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . > [!NOTE] > The order in which the event is raised in relation to the other events may change when the property is not `null`. - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. @@ -610,7 +610,7 @@ Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory would raise two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . > [!NOTE] > The order in which the event is raised in relation to the other events may change when the property is not `null`. @@ -717,7 +717,7 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -790,12 +790,12 @@ to `true`. + The component will not raise events unless you set to `true`. > [!NOTE] -> The component will not watch the specified directory until the property has been set and is `true`. +> The component will not watch the specified directory until the property has been set and is `true`. - The method allows event handlers to be invoked to respond to file changes even if this property is set to `false`. + The method allows event handlers to be invoked to respond to file changes even if this property is set to `false`. @@ -860,7 +860,7 @@ method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. + The Visual Studio 2005 design environment uses this method to end the initialization of a component used on a form or used by another component. The method starts the initialization. Using the and methods prevents the control from being used before it is fully initialized. ]]> @@ -919,10 +919,10 @@ ## Remarks This event is raised whenever something prevents the object from monitoring changes. For example, if the object is monitoring changes in a remote directory and the connection to that directory is lost, the event is raised. - The system notifies you of file changes, and it stores those changes in a buffer that the component creates and passes to the APIs. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer is expensive, because it comes from non paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the , , and properties to filter out unwanted change notifications. + The system notifies you of file changes, and it stores those changes in a buffer that the component creates and passes to the APIs. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer is expensive, because it comes from non paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the , , and properties to filter out unwanted change notifications. > [!NOTE] -> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . +> Common file system operations might raise more than one event. For example, when a file is moved from one directory to another, several and some and events might be raised. Moving a file is a complex operation that consists of multiple simple operations, therefore raising multiple events. Likewise, some applications (for example, antivirus software) might cause additional file system events that are detected by . ]]> @@ -1020,9 +1020,9 @@ The property can be changed after the object has started receiving events. - For more information about filtering out unwanted notifications, see the , , and properties. + For more information about filtering out unwanted notifications, see the , , and properties. - accepts wildcards for matching files, as shown in the following examples. + accepts wildcards for matching files, as shown in the following examples. |Filter string|Watches the following files| |-------------------|---------------------------------| @@ -1145,11 +1145,11 @@ to `true` when you want to watch for change notifications for files and directories contained within the directory specified through the property, and its subdirectories. Setting the property to `false` helps reduce the number of notifications sent to the internal buffer. For more information on filtering out unwanted notifications, see the and properties. + Set to `true` when you want to watch for change notifications for files and directories contained within the directory specified through the property, and its subdirectories. Setting the property to `false` helps reduce the number of notifications sent to the internal buffer. For more information on filtering out unwanted notifications, see the and properties. - When `true`, is recursive through the entire subtree, not just the immediate child directories. The relative path to a file or directory within the subtree returns in the property of and the property of , depending on changes you are watching for. You can get the fully qualified path from the property of and the property of , depending on the changes you are watching for. + When `true`, is recursive through the entire subtree, not just the immediate child directories. The relative path to a file or directory within the subtree returns in the property of and the property of , depending on changes you are watching for. You can get the fully qualified path from the property of and the property of , depending on the changes you are watching for. - If a directory is created in the subtree of the directory you are watching, and is `true`, that directory will automatically be watched. + If a directory is created in the subtree of the directory you are watching, and is `true`, that directory will automatically be watched. ]]> @@ -1225,7 +1225,7 @@ ## Remarks You can set the buffer to 4 KB or larger, but it must not exceed 64 KB. If you try to set the property to less than 4096 bytes, your value is discarded and the property is set to 4096 bytes. For best performance, use a multiple of 4 KB on Intel-based computers. - The system notifies the component of file changes, and it stores those changes in a buffer the component creates and passes to the APIs. Each event can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer can prevent missing file system change events. However, increasing buffer size is expensive, because it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the and properties to filter out unwanted change notifications. + The system notifies the component of file changes, and it stores those changes in a buffer the component creates and passes to the APIs. Each event can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer can prevent missing file system change events. However, increasing buffer size is expensive, because it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To avoid a buffer overflow, use the and properties to filter out unwanted change notifications. ]]> @@ -1296,7 +1296,7 @@ ## Remarks You can combine the members of the enumeration to watch for more than one type of change at a time. For example, you can watch for changes in size of a file, and for changes in the `LastWrite` time. This raises an event anytime there is a change in file or folder size, or a change in the `LastWrite` time of the file or folder. - This is one way to filter out unwanted notifications. For more information on filtering out unwanted notifications, see the , , and properties. + This is one way to filter out unwanted notifications. For more information on filtering out unwanted notifications, see the , , and properties. @@ -1363,11 +1363,11 @@ is called when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. + is called when changes are made to the size, system attributes, last write time, last access time, or security permissions of a file or directory in the directory being monitored. Use the property to restrict the number of events raised when the event is handled. - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1429,11 +1429,11 @@ is called when a file or directory is created in the directory being monitored. + is called when a file or directory is created in the directory being monitored. Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" and paste it into "Your Documents", a event will be raised in FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised in FileSystemWatcher2 and a event would be raised in FileSystemWatcher1. - The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. + The event is raised as soon as a file is created. If a file is being copied or transferred into a watched directory, the event will be raised immediately, followed by one or more events. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1495,7 +1495,7 @@ is called when a file or directory, within the directory being monitored, is deleted. + is called when a file or directory, within the directory being monitored, is deleted. Some common occurrences, such as copying or moving a file or directory, do not correspond directly to an event, but these occurrences do cause events to be raised. When you copy a file or directory, the system raises a event in the directory to which the file was copied, if that directory is being watched. If the directory from which you copied was being watched by another instance of , no event would be raised. For example, you create two instances of . FileSystemWatcher1 is set to watch "C:\My Documents", and FileSystemWatcher2 is set to watch "C:\Your Documents". If you copy a file from "My Documents" into "Your Documents", a event will be raised by FileSystemWatcher2, but no event is raised for FileSystemWatcher1. Unlike copying, moving a file or directory raises two events. From the previous example, if you moved a file from "My Documents" to "Your Documents", a event would be raised by FileSystemWatcher2 and a event would be raised by FileSystemWatcher1. @@ -1559,7 +1559,7 @@ is called when an error occurs. + is called when an error occurs. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1621,7 +1621,7 @@ is called when a file or directory within the directory being monitored is renamed. Its argument contains information about the renaming operation, such as the type of change, the old and new path, and the old and new name. Note that its property may be null for renamed events if the does not get matching old and new name events from the operating system. + is called when a file or directory within the directory being monitored is renamed. Its argument contains information about the renaming operation, such as the type of change, the old and new path, and the old and new name. Note that its property may be null for renamed events if the does not get matching old and new name events from the operating system. Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). @@ -1890,7 +1890,7 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) to a and enable communication between them, as well as provide a way for the container to manage its components. + Sites bind a to a and enable communication between them, as well as provide a way for the container to manage its components. ]]> @@ -1958,11 +1958,11 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) is `null`, methods handling the , , , and events are called on a thread from the system thread pool. For more information on system thread pools, see . + When is `null`, methods handling the , , , and events are called on a thread from the system thread pool. For more information on system thread pools, see . - When the , , , and events are handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or may result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods that handle the , , , and events to be called on the same thread on which the component was created. + When the , , , and events are handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or may result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods that handle the , , , and events to be called on the same thread on which the component was created. - If the is used inside Visual Studio 2005 in a Windows Forms designer, automatically sets to the control that contains the . For example, if you place a on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. + If the is used inside Visual Studio 2005 in a Windows Forms designer, automatically sets to the control that contains the . For example, if you place a on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. ]]> @@ -2033,7 +2033,7 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) with the `timeout` parameter set to -1. + This method waits indefinitely until the first change occurs and then returns. This is the same as using with the `timeout` parameter set to -1. > [!NOTE] > This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. diff --git a/xml/System.IO/IOException.xml b/xml/System.IO/IOException.xml index 95d89229e9d..5fa831e91c1 100644 --- a/xml/System.IO/IOException.xml +++ b/xml/System.IO/IOException.xml @@ -104,7 +104,7 @@ uses the HRESULT COR_E_IO, which has the value 0x80131620. ## Examples - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileStream/.ctor/fstreamlock.vb" id="Snippet6"::: @@ -364,10 +364,10 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> diff --git a/xml/System.IO/InternalBufferOverflowException.xml b/xml/System.IO/InternalBufferOverflowException.xml index e049e12a142..fc0348068c1 100644 --- a/xml/System.IO/InternalBufferOverflowException.xml +++ b/xml/System.IO/InternalBufferOverflowException.xml @@ -60,7 +60,7 @@ , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + In a , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. @@ -134,7 +134,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> @@ -188,7 +188,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> @@ -300,7 +300,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> diff --git a/xml/System.IO/MemoryStream.xml b/xml/System.IO/MemoryStream.xml index e4f23e6b33e..009eeef893e 100644 --- a/xml/System.IO/MemoryStream.xml +++ b/xml/System.IO/MemoryStream.xml @@ -91,13 +91,13 @@ method. When a new instance of is created, the current position is set to zero. + The current position of a stream is the position at which the next read or write operation could take place. The current position can be retrieved or set through the method. When a new instance of is created, the current position is set to zero. [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] Memory streams created with an unsigned byte array provide a non-resizable stream of the data. When using a byte array, you can neither append to nor shrink the stream, although you might be able to modify the existing contents depending on the parameters passed into the constructor. Empty memory streams are resizable, and can be written to and read from. - If a object is added to a ResX file or a .resources file, call the method at runtime to retrieve it. + If a object is added to a ResX file or a .resources file, call the method at runtime to retrieve it. If a object is serialized to a resource file it will actually be serialized as an . This behavior provides better performance, as well as the ability to get a pointer to the data directly, without having to go through methods. @@ -175,11 +175,11 @@ , , and properties are all set to `true`. + The , , and properties are all set to `true`. - The capacity of the current stream automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. + The capacity of the current stream automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. - This constructor exposes the underlying stream, which returns. + This constructor exposes the underlying stream, which returns. ]]> @@ -246,11 +246,11 @@ , , and properties are all set to `true`. is set to the length of the specified byte array. The new stream can be written to, but is not resizable. + The , , and properties are all set to `true`. is set to the length of the specified byte array. The new stream can be written to, but is not resizable. - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - This constructor does not expose the underlying stream. throws . + This constructor does not expose the underlying stream. throws . ]]> @@ -313,11 +313,11 @@ , , and properties are all set to `true`. + The , , and properties are all set to `true`. - The capacity automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. + The capacity automatically increases when you use the method to set the length to a value larger than the capacity of the current stream. Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. - This constructor exposes the underlying stream that returns. + This constructor exposes the underlying stream that returns. ## Examples This code example is part of a larger example provided for the class. @@ -392,11 +392,11 @@ In .NET 11 and later versions, is greater than and properties are both set to `true`. is set to the length of the specified byte array. + The and properties are both set to `true`. is set to the length of the specified byte array. - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - This constructor does not expose the underlying stream. throws . + This constructor does not expose the underlying stream. throws . ]]> @@ -463,11 +463,11 @@ In .NET 11 and later versions, is greater than , , and properties are all set to `true`, but the capacity cannot be changed. is set to `count`. + The , , and properties are all set to `true`, but the capacity cannot be changed. is set to `count`. - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - This constructor does not expose the underlying stream. throws . However, you can write to the stream. + This constructor does not expose the underlying stream. throws . However, you can write to the stream. ]]> @@ -541,9 +541,9 @@ In .NET 11 and later versions, is greater than and properties are both set to `true`. is set to `count`. - The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). - This constructor does not expose the underlying stream. throws . However, you can write to the stream if `writable` is `true`. + This constructor does not expose the underlying stream. throws . However, you can write to the stream if `writable` is `true`. ]]> @@ -619,7 +619,7 @@ In .NET 11 and later versions, is greater than and properties are both set to `true`. is set to `count`. - The new stream instance can be written to, but the of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). + The new stream instance can be written to, but the of the underlying byte array cannot be changed. The length of the stream cannot be set to a value greater than the initial length of the specified byte array; however, the stream can be truncated (see ). ]]> @@ -706,7 +706,7 @@ In .NET 11 and later versions, is greater than remarks for additional usage information for this method. +Refer to the remarks for additional usage information for this method. ]]> @@ -789,7 +789,7 @@ Refer to the remarks for additional usage i ## Remarks -Refer to the remarks for additional usage information for this method. +Refer to the remarks for additional usage information for this method. ]]> @@ -852,7 +852,7 @@ Refer to the remarks for additional usage does not support reading, calls to the and methods throw a . + If a class derived from does not support reading, calls to the and methods throw a . If the stream is closed, this property returns `false`. @@ -916,7 +916,7 @@ Refer to the remarks for additional usage does not support seeking, calls to , , , and throw a . + If a class derived from does not support seeking, calls to , , , and throw a . If the stream is closed, this property returns `false`. @@ -980,7 +980,7 @@ Refer to the remarks for additional usage does not support writing, a call to , , or throws a . + If a class derived from does not support writing, a call to , , or throws a . If the stream is closed, this property returns `false`. @@ -1307,7 +1307,7 @@ The stream is unwritable. method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -1370,7 +1370,7 @@ The stream is unwritable. ## Remarks -Refer to the remarks for additional usage information for this method. +Refer to the remarks for additional usage information for this method. ]]> @@ -1434,7 +1434,7 @@ The pending operation does not support reading. ## Remarks -Refer to the remarks for additional usage information for this method. +Refer to the remarks for additional usage information for this method. ]]> @@ -1502,7 +1502,7 @@ The pending operation does not support writing. method. + This method overrides the method. Because any data written to a object is written into RAM, this method is redundant. @@ -1644,11 +1644,11 @@ The pending operation does not support writing. object, the length of the buffer returned from is 256, not 4, with 252 bytes unused. To obtain only the data in the buffer, use the method; however, creates a copy of the data in memory. + Note that the buffer contains allocated bytes which might be unused. For example, if the string "test" is written into the object, the length of the buffer returned from is 256, not 4, with 252 bytes unused. To obtain only the data in the buffer, use the method; however, creates a copy of the data in memory. The buffer can also be `null`. - To create a `MemoryStream` instance with a publicly visible buffer, use , , or . If the current stream is resizable, two calls to this method do not return the same array if the underlying byte array is resized between calls. For additional information, see . + To create a `MemoryStream` instance with a publicly visible buffer, use , , or . If the current stream is resizable, two calls to this method do not return the same array if the underlying byte array is resized between calls. For additional information, see . > [!NOTE] > This method works when the memory stream is closed. @@ -1958,7 +1958,7 @@ The pending operation does not support writing. . + This method overrides . The `offset` parameter gives the offset of the first byte in `buffer` to which data from the current stream is written. The `count` parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached. @@ -1969,7 +1969,7 @@ The pending operation does not support writing. Use for reading primitive data types. > [!CAUTION] -> If the byte array specified in the `buffer` parameter is the underlying buffer returned by the method, the array contents are overwritten, and no exception is thrown. +> If the byte array specified in the `buffer` parameter is the underlying buffer returned by the method, the array contents are overwritten, and no exception is thrown. @@ -2185,7 +2185,7 @@ The pending operation does not support writing. . + This method overrides . If the read operation is successful, the current position within the stream is advanced by one byte. If an exception occurs, the current position within the stream is unchanged. @@ -2263,11 +2263,11 @@ The pending operation does not support writing. . + This method overrides . Seeking to any location beyond the length of the stream is supported. - Do not use the method to determine the new position in the stream if the was initialized with a non-zero offset. If you do, will return an inaccurate value. Instead, use the property to get the new position of the stream. + Do not use the method to determine the new position in the stream if the was initialized with a non-zero offset. If you do, will return an inaccurate value. Instead, use the property to get the new position of the stream. @@ -2347,9 +2347,9 @@ The pending operation does not support writing. . +This method overrides . -If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the method returns -1, the method reads zero bytes into the provided byte array, and and methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros. +If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the method returns -1, the method reads zero bytes into the provided byte array, and and methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros. > [!NOTE] > A instance must support writing for this method to work. Use the property to determine whether the current instance supports writing. For additional information, see . @@ -2435,7 +2435,7 @@ In .NET 10 and earlier versions, is greater than the m from the array. To get the entire buffer, use the method. + This method omits unused bytes in from the array. To get the entire buffer, use the method. This method returns a copy of the contents of the as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the constructor for details. @@ -2639,7 +2639,7 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance . + This method overrides . The `offset` parameter gives the offset of the first byte in `buffer` to write from, and the `count` parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged. @@ -2867,7 +2867,7 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance . + This method overrides . Except for a `MemoryStream` constructed with a byte[] parameter, write operations at the end of a `MemoryStream` expand the `MemoryStream`. @@ -2947,7 +2947,7 @@ The underlying buffer will not be exposed if the current `MemoryStream` instance on the underlying buffer of this stream. + When the current stream is open, this method is equivalent to calling on the underlying buffer of this stream. ]]> diff --git a/xml/System.IO/Path.xml b/xml/System.IO/Path.xml index 61c440309be..60d1e35ea6a 100644 --- a/xml/System.IO/Path.xml +++ b/xml/System.IO/Path.xml @@ -80,26 +80,26 @@ A path is a string that provides the location of a file or directory. A path does not necessarily point to a location on disk; for example, a path might map to a location in memory or on a device. The exact format of a path is determined by the current platform. For example, on some systems, a path can start with a drive or volume letter, while this element is not present in other systems. On some systems, file paths can contain extensions, which indicate the type of information stored in the file. The format of a file name extension is platform-dependent; for example, some systems limit extensions to three characters (such as FAT16 commonly used on smaller flash storage and older versions of ISO 9660 used on optical media), and others do not. The current platform also determines the set of characters used to separate the elements of a path, and the set of characters that cannot be used when specifying paths. Because of these differences, the fields of the `Path` class as well as the exact behavior of some members of the `Path` class are platform-dependent. - A path can contain absolute or relative location information. Absolute paths fully specify a location: the file or directory can be uniquely identified regardless of the current location. Relative paths specify a partial location: the current location is used as the starting point when locating a file specified with a relative path. To determine the current directory, call . + A path can contain absolute or relative location information. Absolute paths fully specify a location: the file or directory can be uniquely identified regardless of the current location. Relative paths specify a partial location: the current location is used as the starting point when locating a file specified with a relative path. To determine the current directory, call . This type also supports access to file system objects that are device names, such as "\\\\?\\C:\\". Device name support was added in .NET Framework 4.6.2. For more information on file path formats on Windows, see [File path formats on Windows systems](/dotnet/standard/io/file-path-formats). - Most members of the `Path` class do not interact with the file system and do not verify the existence of the file specified by a path string. `Path` class members that modify a path string, such as , have no effect on names of files in the file system. + Most members of the `Path` class do not interact with the file system and do not verify the existence of the file specified by a path string. `Path` class members that modify a path string, such as , have no effect on names of files in the file system. - Some `Path` members do validate the contents of a specified path string, and throw an if the string contains characters that are not valid in path strings, as defined in the characters returned from the method. For example, on Windows-based desktop platforms, invalid path characters might include quote ("), less than (\<), greater than (>), pipe (|), backspace (\\b), null (\\0), and Unicode characters 16 through 18 and 20 through 25. This validation behavior varies between .NET versions: + Some `Path` members do validate the contents of a specified path string, and throw an if the string contains characters that are not valid in path strings, as defined in the characters returned from the method. For example, on Windows-based desktop platforms, invalid path characters might include quote ("), less than (\<), greater than (>), pipe (|), backspace (\\b), null (\\0), and Unicode characters 16 through 18 and 20 through 25. This validation behavior varies between .NET versions: - On .NET Framework: All `Path` members that take a path as an argument throw an if they detect invalid path characters. - - On .NET: is the only member that throws an if the string contains invalid path characters. + - On .NET: is the only member that throws an if the string contains invalid path characters. The members of the `Path` class enable you to quickly and easily perform common operations such as determining whether a file name extension is part of a path, and combining two strings into one path name. All members of the `Path` class are static and can therefore be called without having an instance of a path. > [!NOTE] -> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\\temp c:\\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. +> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\\temp c:\\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: @@ -111,7 +111,7 @@ For more information on file path formats on Windows, see [File path formats on - "\\\\\\\\MyServer\\\\MyShare" in C#, or "\\\\MyServer\\MyShare" in Visual Basic. - Because all these operations are performed on strings, it is impossible to verify that the results are valid in all scenarios. For example, the method parses a string that you pass to it and returns the extension from that string. However, this does not mean that a file with that extension exists on the disk. + Because all these operations are performed on strings, it is impossible to verify that the results are valid in all scenarios. For example, the method parses a string that you pass to it and returns the extension from that string. However, this does not mean that a file with that extension exists on the disk. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -300,10 +300,10 @@ The following example displays field values on Windows and ## Remarks -This method is intended to concatenate individual strings into a single string that represents a file path. However, if an argument other than the first contains a rooted path, any previous path components are ignored, and the returned string begins with that rooted path component. As an alternative to the `Combine` method, consider using the or methods (not available in .NET Framework). +This method is intended to concatenate individual strings into a single string that represents a file path. However, if an argument other than the first contains a rooted path, any previous path components are ignored, and the returned string begins with that rooted path component. As an alternative to the `Combine` method, consider using the or methods (not available in .NET Framework). > [!IMPORTANT] -> This method assumes that the first argument is an absolute path and that the following argument or arguments are relative paths. If this is not the case, and particularly if any subsequent arguments are strings input by the user, call the or method instead. +> This method assumes that the first argument is an absolute path and that the following argument or arguments are relative paths. If this is not the case, and particularly if any subsequent arguments are strings input by the user, call the or method instead. ]]> @@ -506,7 +506,7 @@ If any element in `paths` but the last one is not a drive and does not end with If `path2` does not include a root (for example, if `path2` does not start with a separator character or a drive specification), the result is a concatenation of the two paths, with an intervening separator character. If `path2` includes a root, `path2` is returned. - The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1` instead of returning only `path2`. + The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1` instead of returning only `path2`. .NET Framework and .NET Core versions older than 2.1: Not all invalid characters for directory and file names are interpreted as unacceptable by the `Combine` method, because you can use these characters for search wildcard characters. For example, while `Path.Combine("c:\\", "*.txt")` might be invalid if you were to create a file from it, it is valid as a search string. It is therefore successfully interpreted by the `Combine` method. @@ -594,7 +594,7 @@ If any element in `paths` but the last one is not a drive and does not end with If `path2` does not include a root (for example, if `path2` does not start with a separator character or a drive specification), the result is a concatenation of the two paths, with an intervening separator character. If `path2` includes a root, `path2` is returned. - The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1`. + The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1`. .NET Framework and .NET Core versions older than 2.1: Not all invalid characters for directory and file names are interpreted as unacceptable by the `Combine` method, because you can use these characters for search wildcard characters. For example, while `Path.Combine("c:\\", "*.txt")` might be invalid if you were to create a file from it, it is valid as a search string. It is therefore successfully interpreted by the `Combine` method. @@ -679,7 +679,7 @@ If any element in `paths` but the last one is not a drive and does not end with If `path2` does not include a root (for example, if `path2` does not start with a separator character or a drive specification), the result is a concatenation of the two paths, with an intervening separator character. If `path2` includes a root, `path2` is returned. - The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1`. + The parameters are not parsed if they have white space. Therefore, if `path2` includes white space (for example, " \\file.txt "), the method appends `path2` to `path1`. .NET Framework and .NET Core versions older than 2.1: Not all invalid characters for directory and file names are interpreted as unacceptable by the `Combine` method, because you can use these characters for search wildcard characters. For example, while `Path.Combine("c:\\", "*.txt")` might be invalid if you were to create a file from it, it is valid as a search string. It is therefore successfully interpreted by the `Combine` method. @@ -1053,7 +1053,7 @@ In most cases, the string returned by this method consists of all characters in This method does not support paths using "file:". -Because the returned path does not include the last directory separator character(s), passing the returned path back into the method truncates one folder level per subsequent call on the result path. For example, passing the path "C:\\Directory\\SubDirectory\\test.txt" into returns "C:\\Directory\\SubDirectory". Passing that path, "C:\\Directory\\SubDirectory", into returns "C:\\Directory". +Because the returned path does not include the last directory separator character(s), passing the returned path back into the method truncates one folder level per subsequent call on the result path. For example, passing the path "C:\\Directory\\SubDirectory\\test.txt" into returns "C:\\Directory\\SubDirectory". Passing that path, "C:\\Directory\\SubDirectory", into returns "C:\\Directory". For a list of common I/O tasks, see [Common I/O tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1119,7 +1119,7 @@ Note: In or character, the returned read-only span contains the period and the characters after it; otherwise, is returned. +This method obtains the extension of `path` by searching `path` for a period ("."), starting from the last character in the read-only span and continuing toward its first character. If a period is found before a or character, the returned read-only span contains the period and the characters after it; otherwise, is returned. ]]> @@ -1243,7 +1243,7 @@ This method obtains the extension of `path` by searching `path` for a period (.) . If `path` contains no separator character, the method returns `path`. +The returned read-only span contains the characters of the path that follow the last separator in `path`. If the last character in `path` is a volume or directory separator character, the method returns . If `path` contains no separator character, the method returns `path`. ]]> @@ -1513,7 +1513,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The file or directory specified by `path` is not required to exist. For example, if *c:\\temp\\newdir* is the current directory, calling `GetFullPath` on a file name such as *test.txt* returns *c:\\temp\\newdir\\test.txt*. The file need not exist. > [!IMPORTANT] -> If `path` is a relative path, this overload returns a fully qualified path that can be based on the current drive and current directory. The current drive and current directory can change at any time as an application executes. As a result, the path returned by this overload cannot be determined in advance. To return a deterministic path, call the overload. You can also call the method to determine whether a path is fully qualified or relative and therefore whether a call to `GetFullPath` is necessary. +> If `path` is a relative path, this overload returns a fully qualified path that can be based on the current drive and current directory. The current drive and current directory can change at any time as an application executes. As a result, the path returned by this overload cannot be determined in advance. To return a deterministic path, call the overload. You can also call the method to determine whether a path is fully qualified or relative and therefore whether a call to `GetFullPath` is necessary. However, if `path` does exist, the caller must have permission to obtain path information for `path`. Note that unlike most members of the class, this method accesses the file system. @@ -1677,7 +1677,7 @@ The following example defines a variable, `basePath`, to represent an applicatio ## Examples - The following example demonstrates the method and the method to retrieve invalid characters. + The following example demonstrates the method and the method to retrieve invalid characters. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/GetInvalidFileNameChars/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Path/GetInvalidFileNameChars/example.vb" id="Snippet1"::: @@ -1738,7 +1738,7 @@ The following example defines a variable, `basePath`, to represent an applicatio The array returned from this method is not guaranteed to contain the complete set of characters that are invalid in file and directory names. The full set of invalid characters can vary by file system. For example, on Windows-based desktop platforms, invalid path characters might include ASCII/Unicode characters 1 through 31, as well as pipe (|) and null (\\0). ## Examples - The following example demonstrates the method and the method to retrieve invalid characters. + The following example demonstrates the method and the method to retrieve invalid characters. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/GetInvalidFileNameChars/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Path/GetInvalidFileNameChars/example.vb" id="Snippet1"::: @@ -1798,14 +1798,14 @@ Unlike the string overload, this method doesn't normalize directory separators. A `ReadOnlySpan` is "effectively empty" if: -- In Windows, calling on this span of characters returns `true`, or all its characters are spaces (' '). -- In Unix, calling on this span of characters returns `true`. +- In Windows, calling on this span of characters returns `true`, or all its characters are spaces (' '). +- In Unix, calling on this span of characters returns `true`. Possible patterns for the read-only character span returned by this method are as follows: -- (`path` was . +- (`path` was . -- (`path` specified a relative path on the current drive or volume). +- (`path` specified a relative path on the current drive or volume). - "/" (Unix: `path` specified an absolute path on the current drive). @@ -1901,7 +1901,7 @@ This method will normalize directory separators. A string is "effectively empty" if: - In Windows, calling `IsEmpty` on this string returns `true`, or all its characters are spaces (' '). -- In Unix, calling on this string returns `true`. +- In Unix, calling on this string returns `true`. Possible patterns for the string returned by this method are as follows: @@ -1990,11 +1990,11 @@ The following example demonstrates a use of the `GetPathRoot` method. ## Remarks -Unlike , does not create a file. +Unlike , does not create a file. ## Examples - The following example show output from the method. + The following example show output from the method. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/ChangeExtension/pathmembers20.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Path/ChangeExtension/pathmembers20.vb" id="Snippet20"::: @@ -2049,10 +2049,10 @@ Unlike , method before calculating the difference. The method uses the default file path comparison for the current platform ( for Windows and macOS, for Linux). +Paths are resolved by calling the method before calculating the difference. The method uses the default file path comparison for the current platform ( for Windows and macOS, for Linux). ## Examples - The following code shows how to call the method. + The following code shows how to call the method. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/GetRelativePath/GetRelativePath.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Path/GetRelativePath/GetRelativePath.vb" id="Snippet1"::: @@ -2122,11 +2122,11 @@ Paths are resolved by calling the method be ## Remarks -This method creates a temporary file with a *.tmp* file extension and returns the path to it. The temporary file is created within the user's temporary folder, which is the path returned by the method. +This method creates a temporary file with a *.tmp* file extension and returns the path to it. The temporary file is created within the user's temporary folder, which is the path returned by the method. On .NET Framework, the method raises an if it's used to create more than 65535 files without deleting previous temporary files. This limitation does not exist on operating systems other than Windows. Starting in .NET 8, the limitation does not exist on *any* operating system. - The method will raise an if no unique temporary file name is available. To resolve this error, delete all unneeded temporary files. + The method will raise an if no unique temporary file name is available. To resolve this error, delete all unneeded temporary files. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2222,7 +2222,7 @@ The `/tmp/` directory on Linux is commonly shared among all users (`1777` permis --- ## Examples - The following code shows how to call the method. + The following code shows how to call the method. ```vb Dim result As String = Path.GetTempPath() @@ -2464,7 +2464,7 @@ The array returned from this method is not guaranteed to contain the complete se The overloads of the `IsPathFullyQualified` method handle paths that use both the and the characters. It does not perform any validation on the path that is passed to it as an argument. As a result, URIs are interpreted as relative paths and return `false`. -There is a difference between a fully qualified path (as indicated by the `IsPathFullyQualified` method) and a rooted path (as indicated by the method). A *fully qualified path* or *absolute path* always defines an exact path from a particular drive or device to a target file or directory, and does not depend on the current drive or current directory. For example, on Windows systems, *C:/users/user1/documents/reports/2019/january/highlights.pdf* defines an absolute path from the root of the C: drive to the target file, *highlights.pdf*. A *rooted path* specifies either a starting drive or root directory, but depends on either the current directory (if it is rooted by a specified drive) or the current drive (if it is rooted by the root directory). The following example illustrates the difference between fully qualified paths and rooted paths. +There is a difference between a fully qualified path (as indicated by the `IsPathFullyQualified` method) and a rooted path (as indicated by the method). A *fully qualified path* or *absolute path* always defines an exact path from a particular drive or device to a target file or directory, and does not depend on the current drive or current directory. For example, on Windows systems, *C:/users/user1/documents/reports/2019/january/highlights.pdf* defines an absolute path from the root of the C: drive to the target file, *highlights.pdf*. A *rooted path* specifies either a starting drive or root directory, but depends on either the current directory (if it is rooted by a specified drive) or the current drive (if it is rooted by the root directory). The following example illustrates the difference between fully qualified paths and rooted paths. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/IsPathRooted/Program.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.IO/Path/IsPathRooted/program.vb"::: @@ -2704,7 +2704,7 @@ Note that rooted paths can be either absolute (that is, fully qualified) or rela method returns `true` if the first character is a directory separator character such as "\\", or if the path starts with a drive letter and colon (:). For example, it returns `true` for `path` strings such as "\\\\MyDir\\MyFile.txt", "C:\\MyDir", or "C:MyDir". It returns `false` for `path` strings such as "MyDir". + The method returns `true` if the first character is a directory separator character such as "\\", or if the path starts with a drive letter and colon (:). For example, it returns `true` for `path` strings such as "\\\\MyDir\\MyFile.txt", "C:\\MyDir", or "C:MyDir". It returns `false` for `path` strings such as "MyDir". This method does not verify that the path or file name exists. @@ -2839,7 +2839,7 @@ If any of the paths in `paths`, except for the last one, ends in a path separato - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if any of the paths in `paths`, except for the first one, is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if any of the paths in `paths`, except for the first one, is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. @@ -2900,7 +2900,7 @@ Not all invalid characters for directory and file names are interpreted as unacc ## Remarks -This method simply concatenates `path` and `path2` and adds a directory separator character between the two path components if one is not already present at the end of `path1` or the beginning of `path2`. If the of either `path1` or `path2` is zero, the method returns the other path. If the of both `path1` and `path2` is zero, the method returns . +This method simply concatenates `path` and `path2` and adds a directory separator character between the two path components if one is not already present at the end of `path1` or the beginning of `path2`. If the of either `path1` or `path2` is zero, the method returns the other path. If the of both `path1` and `path2` is zero, the method returns . If `path1` ends in a path separator character that is not appropriate for the target platform, the `Join` method preserves the original path separator character and appends the supported one. This issue arises in hard-coded paths that use the Windows backslash ("\\") character, which is not recognized as a path separator on Unix-based systems. To work around this issue, you can: @@ -2908,13 +2908,13 @@ If `path1` ends in a path separator character that is not appropriate for the ta - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` is an absolute path, the `Join` method does not discard `path1` and return `path2` as the method does.) The following example illustrates the difference in the paths returned by the two methods. If the source of `path2` is user input, the method makes it possible for a user to access a file system resource (such as *C:/Users/User1/Documents/Financial/* in the case of the example) that the application did not intend to make accessible. +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` is an absolute path, the `Join` method does not discard `path1` and return `path2` as the method does.) The following example illustrates the difference in the paths returned by the two methods. If the source of `path2` is user input, the method makes it possible for a user to access a file system resource (such as *C:/Users/User1/Documents/Financial/* in the case of the example) that the application did not intend to make accessible. Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. ## Examples -The following example illustrates the difference in the paths returned by the and methods. When the first string is an fully qualified path that includes a drive and root directory and the second is a relative path from the first path, the two methods produce identical results. In the second and third calls to the `ShowPathInformation` method, the strings returned by the two methods diverge. In the second method call, the first string argument is a drive, while the second is a rooted directory. The `Join` method concatenates the two strings and preserves duplicate path separators. The `Combine` method abandons the drive and returns a rooted directory on the current drive. If the application's current drive is C:\\ and the string is used to access a file or files in the directory, it would access C: instead of D:. Finally, because both arguments in the third call to `ShowPathInformation` are rooted, the `Join` method simply appends them to create a nonsensical file path, while the `Combine` method discards the first string and returns the second. Using this string for file access could give the application unintended access to sensitive files. +The following example illustrates the difference in the paths returned by the and methods. When the first string is an fully qualified path that includes a drive and root directory and the second is a relative path from the first path, the two methods produce identical results. In the second and third calls to the `ShowPathInformation` method, the strings returned by the two methods diverge. In the second method call, the first string argument is a drive, while the second is a rooted directory. The `Join` method concatenates the two strings and preserves duplicate path separators. The `Combine` method abandons the drive and returns a rooted directory on the current drive. If the application's current drive is C:\\ and the string is used to access a file or files in the directory, it would access C: instead of D:. Finally, because both arguments in the third call to `ShowPathInformation` are rooted, the `Join` method simply appends them to create a nonsensical file path, while the `Combine` method discards the first string and returns the second. Using this string for file access could give the application unintended access to sensitive files. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/Combine/Program2.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.io/path/combine2/program.vb"::: @@ -2985,7 +2985,7 @@ If `path1` ends in a path separator character that is not appropriate for the ta - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. @@ -3048,7 +3048,7 @@ Not all invalid characters for directory and file names are interpreted as unacc ## Remarks -This method simply concatenates `path`, `path2`, and `path3` and adds a directory separator character between any of the path components if one is not already present. If the of any of `path1`, `path2`, or `path3` arguments is zero, the method concatenates the remaining arguments. If the of all components is zero, the method returns . +This method simply concatenates `path`, `path2`, and `path3` and adds a directory separator character between any of the path components if one is not already present. If the of any of `path1`, `path2`, or `path3` arguments is zero, the method concatenates the remaining arguments. If the of all components is zero, the method returns . If `path1` or `path2` ends in a path separator character that is not appropriate for the target platform, the `Join` method preserves the original path separator character and appends the supported one. This issue arises in hard-coded paths that use the Windows backslash ("\\") character, which is not recognized as a path separator on Unix-based systems. To work around this issue, you can: @@ -3056,13 +3056,13 @@ If `path1` or `path2` ends in a path separator character that is not appropriate - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. ## Examples -The following example illustrates the difference in the paths returned by the and methods. When the first string is a fully qualified path that includes a drive and root directory and the second is a relative path from the first path, the two methods produce identical results. In the second and third calls to the `ShowPathInformation` method, the strings returned by the two methods diverge. In the second method call, the first string argument is a drive, while the second is a rooted directory. The `Join` method concatenates the two strings and preserves duplicate path separators. A call to the method would eliminate the duplication. The `Combine` method abandons the drive and returns a rooted directory on the current drive. If the application's current drive is C:\\ and the string is used to access a file or files in the directory, it would access C: instead of D:. Finally, because the final argument in the third call to `ShowPathInformation` are rooted, the `Join` method simply appends it to the first two arguments to create a nonsensical file path, while the `Combine` method discards the first two strings and returns the third. Using this string for file access could give the application unintended access to sensitive files. +The following example illustrates the difference in the paths returned by the and methods. When the first string is a fully qualified path that includes a drive and root directory and the second is a relative path from the first path, the two methods produce identical results. In the second and third calls to the `ShowPathInformation` method, the strings returned by the two methods diverge. In the second method call, the first string argument is a drive, while the second is a rooted directory. The `Join` method concatenates the two strings and preserves duplicate path separators. A call to the method would eliminate the duplication. The `Combine` method abandons the drive and returns a rooted directory on the current drive. If the application's current drive is C:\\ and the string is used to access a file or files in the directory, it would access C: instead of D:. Finally, because the final argument in the third call to `ShowPathInformation` are rooted, the `Join` method simply appends it to the first two arguments to create a nonsensical file path, while the `Combine` method discards the first two strings and returns the third. Using this string for file access could give the application unintended access to sensitive files. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/Combine/Program3.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.io/path/combine3/program.vb"::: @@ -3134,7 +3134,7 @@ If `path1` or `path2` ends in a path separator character that is not appropriate - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. @@ -3198,7 +3198,7 @@ Not all invalid characters for directory and file names are interpreted as unacc ## Remarks -This method simply concatenates `path`, `path2`, `path3` and `path4` and adds a directory separator character between any of the path components if one is not already present. If the of any of `path1`, `path2`, `path3` or `path4` argument is zero, the method concatenates the remaining arguments. If the of all components is zero, the method returns . +This method simply concatenates `path`, `path2`, `path3` and `path4` and adds a directory separator character between any of the path components if one is not already present. If the of any of `path1`, `path2`, `path3` or `path4` argument is zero, the method concatenates the remaining arguments. If the of all components is zero, the method returns . If `path1` or `path2` or `path3` ends in a path separator character that is not appropriate for the target platform, the `Join` method preserves the original path separator character and appends the supported one. This issue arises in hard-coded paths that use the Windows backslash ("\\") character, which is not recognized as a path separator on Unix-based systems. To work around this issue, you can: @@ -3206,7 +3206,7 @@ If `path1` or `path2` or `path3` ends in a path separator character that is not - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` or `path4` is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` or `path4` is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. @@ -3278,7 +3278,7 @@ If `path1` or `path2` or `path3` ends in a path separator character that is not - Use a forward slash ("/") as the directory separator character. This character is returned by the property on Unix-based systems and by the property on Windows systems. -Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` or `path4` is an absolute path, the `Join` method does not discard the previous paths as the method does.) +Unlike the method, the method does not attempt to root the returned path. (That is, if `path2` or `path3` or `path4` is an absolute path, the `Join` method does not discard the previous paths as the method does.) Not all invalid characters for directory and file names are interpreted as unacceptable by the `Join` method, because you can use these characters for search wildcard characters. For example, while `Path.Join("c:\\", "temp", "*.txt")` might be invalid when creating a file, it is valid as a search string. The `Join` method therefore successfully interprets it. @@ -3442,7 +3442,7 @@ Not all invalid characters for directory and file names are interpreted as unacc ## Remarks -The destination character span must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the following example illustrates. +The destination character span must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.IO/Path/TryJoin/Program.cs"::: @@ -3502,7 +3502,7 @@ The destination character span must be large enough to hold the concatenated pat ## Remarks -`destination` must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the example illustrates. +`destination` must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the example illustrates. ]]> @@ -3563,7 +3563,7 @@ The destination character span must be large enough to hold the concatenated pat ## Remarks -`destination` must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the example illustrates. +`destination` must be large enough to hold the concatenated path. You can then retrieve the concatenated path by calling the method, as the example illustrates. ]]> diff --git a/xml/System.IO/PathTooLongException.xml b/xml/System.IO/PathTooLongException.xml index d33c375c1a2..03efe1a9271 100644 --- a/xml/System.IO/PathTooLongException.xml +++ b/xml/System.IO/PathTooLongException.xml @@ -318,10 +318,10 @@ |Property|Value| |--------------|-----------| -||The inner exception reference.| -||The error message string.| +||The inner exception reference.| +||The error message string.| - For more information on inner exceptions, see . + For more information on inner exceptions, see . ]]> diff --git a/xml/System.IO/Stream.xml b/xml/System.IO/Stream.xml index 004c939c6e2..e25649f081e 100644 --- a/xml/System.IO/Stream.xml +++ b/xml/System.IO/Stream.xml @@ -111,19 +111,19 @@ Some of the more commonly used streams that inherit from are , and . - Depending on the underlying data source or repository, streams might support only some of these capabilities. You can query a stream for its capabilities by using the , , and properties of the class. + Depending on the underlying data source or repository, streams might support only some of these capabilities. You can query a stream for its capabilities by using the , , and properties of the class. - The and methods read and write data in a variety of formats. For streams that support seeking, use the and methods and the and properties to query and modify the current position and length of a stream. + The and methods read and write data in a variety of formats. For streams that support seeking, use the and methods and the and properties to query and modify the current position and length of a stream. - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - Disposing a object flushes any buffered data, and essentially calls the method for you. also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance. + Disposing a object flushes any buffered data, and essentially calls the method for you. also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance. - Starting with the .NET Framework 4.5, the class includes async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , and . These methods enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + Starting with the .NET Framework 4.5, the class includes async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , and . These methods enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - When used in a Windows 8.x Store app, includes two extension methods: and . These methods convert a object to a stream in the Windows Runtime. You can also convert a stream in the Windows Runtime to a object by using the and methods. For more information, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](/dotnet/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams) + When used in a Windows 8.x Store app, includes two extension methods: and . These methods convert a object to a stream in the Windows Runtime. You can also convert a stream in the Windows Runtime to a object by using the and methods. For more information, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](/dotnet/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams) - Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, you can use the or method to clear any internal buffers and ensure that all data has been written to the underlying data source or repository. + Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, you can use the or method to clear any internal buffers and ensure that all data has been written to the underlying data source or repository. If you need a stream with no backing store (also known as a bit bucket), use the field to retrieve an instance of a stream that is designed for this purpose. @@ -276,11 +276,11 @@ and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - The default implementation of `BeginRead` on a stream calls the method synchronously, which means that `Read` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginRead` will not block on those streams. You can override `BeginRead` (by using async delegates, for example) to provide asynchronous behavior. + The default implementation of `BeginRead` on a stream calls the method synchronously, which means that `Read` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginRead` will not block on those streams. You can override `BeginRead` (by using async delegates, for example) to provide asynchronous behavior. - Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. + Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. @@ -376,11 +376,11 @@ and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - The default implementation of `BeginWrite` on a stream calls the method synchronously, which means that `Write` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginWrite` will not block on those streams. You can override `BeginWrite` (by using async delegates, for example) to provide asynchronous behavior. + The default implementation of `BeginWrite` on a stream calls the method synchronously, which means that `Write` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginWrite` will not block on those streams. You can override `BeginWrite` (by using async delegates, for example) to provide asynchronous behavior. - Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. + Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. If a stream is writable, writing at the end of the stream expands the stream. @@ -454,7 +454,7 @@ does not support reading, calls to the , , and methods throw a . + If a class derived from does not support reading, calls to the , , and methods throw a . @@ -521,7 +521,7 @@ does not support seeking, calls to , , , and may throw a . + If a class derived from does not support seeking, calls to , , , and may throw a . ]]> @@ -642,7 +642,7 @@ does not support writing, a call to , , or throws a . In such cases, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. + If a class derived from does not support writing, a call to , , or throws a . In such cases, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. @@ -705,9 +705,9 @@ , specifying `true` to release all resources. You do not have to specifically call the method. Instead, ensure that every object is properly disposed. You can declare objects within a `using` block (or `Using` block in Visual Basic) to ensure that the stream and all of its resources are disposed, or you can explicitly call the method. + This method calls , specifying `true` to release all resources. You do not have to specifically call the method. Instead, ensure that every object is properly disposed. You can declare objects within a `using` block (or `Using` block in Visual Basic) to ensure that the stream and all of its resources are disposed, or you can explicitly call the method. - Flushing the stream will not flush its underlying encoder unless you explicitly call an implementation of or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call an implementation of or `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. Attempts to manipulate the stream after the stream has been closed might throw an . @@ -947,7 +947,7 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Copying begins at the current position in the current stream. @@ -1026,11 +1026,11 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Copying begins at the current position in the current stream. - For an example of copying between two streams, see the overload. + For an example of copying between two streams, see the overload. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1090,13 +1090,13 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. If the operation is canceled before it completes, the returned task contains the value for the property. Copying begins at the current position in the current stream. - For an example of copying between two streams, see the overload. + For an example of copying between two streams, see the overload. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1166,13 +1166,13 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. If the operation is canceled before it completes, the returned task contains the value for the property. Copying begins at the current position in the current stream. - For an example of copying between two streams, see the overload. + For an example of copying between two streams, see the overload. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1250,7 +1250,7 @@ ## Remarks When called for the first time, the current method creates a `WaitHandle` object and returns it. On subsequent calls, `CreateWaitHandle` returns a reference to a new wait handle. - Use this method if you implement the asynchronous methods and require a way of blocking in or until the asynchronous operation is complete. + Use this method if you implement the asynchronous methods and require a way of blocking in or until the asynchronous operation is complete. ]]> @@ -1390,7 +1390,7 @@ If your stream is using an operating system handle to communicate with its source, consider using a subclass of for this purpose. - This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. ]]> @@ -1447,7 +1447,7 @@ method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. This method disposes the stream by writing any changes to the backing store and closing the stream to release resources. @@ -1509,11 +1509,11 @@ and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. Call `EndRead` to determine how many bytes were read from the stream. - `EndRead` can be called once on every from . + `EndRead` can be called once on every from . This method blocks until the I/O operation has completed. @@ -1584,9 +1584,9 @@ and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + In the .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - `EndWrite` must be called exactly once on every from . + `EndWrite` must be called exactly once on every from . This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to `EndWrite`. Exceptions thrown by the thread pool thread will not be visible when calling `EndWrite`. @@ -1657,11 +1657,11 @@ . + Override `Flush` on streams that implement a buffer. Use this method to move any information from an underlying buffer to its destination, clear the buffer, or both. Depending upon the state of the object, you might have to modify the current position within the stream (for example, if the underlying stream supports seeking). For additional information see . - In a class derived from that doesn't support writing, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. + In a class derived from that doesn't support writing, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. - When using the or class, do not flush the base object. Instead, use the class's or method, which makes sure that the data is flushed to the underlying stream first and then written to the file. + When using the or class, do not flush the base object. Instead, use the class's or method, which makes sure that the data is flushed to the underlying stream first and then written to the file. ]]> @@ -1736,7 +1736,7 @@ or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. + If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1804,7 +1804,7 @@ ## Remarks If the operation is canceled before it completes, the returned task contains the value for the property. - If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. + If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -2081,9 +2081,9 @@ property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. - Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. Use for reading primitive data types. @@ -2149,16 +2149,16 @@ property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. - Implementations of this method read a maximum of `count` bytes from the current stream and store them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (some implementations may similarly not complete until at least one byte is available even if zero bytes were requested, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + Implementations of this method read a maximum of `count` bytes from the current stream and store them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (some implementations may similarly not complete until at least one byte is available even if zero bytes were requested, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. Use for reading primitive data types. ## Examples - The following example shows how to use to read a block of data. + The following example shows how to use to read a block of data. :::code language="csharp" source="~/snippets/csharp/System.IO/Stream/Read/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/Stream/Read/source.vb" id="Snippet1"::: @@ -2234,13 +2234,13 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. - For an example, see the overload. + For an example, see the overload. ]]> @@ -2308,7 +2308,7 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports reading. @@ -2395,13 +2395,13 @@ method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. - For an example, see the overload. + For an example, see the overload. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3264,7 +3264,7 @@ This member is an explicit interface member implementation. It can be used only property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. @@ -3328,7 +3328,7 @@ This member is an explicit interface member implementation. It can be used only property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. @@ -3404,13 +3404,13 @@ This member is an explicit interface member implementation. It can be used only method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports writing. If the operation is canceled before it completes, the returned task contains the value for the property. - For an example, see the overload. + For an example, see the overload. ]]> @@ -3478,7 +3478,7 @@ This member is an explicit interface member implementation. It can be used only method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports writing. @@ -3565,13 +3565,13 @@ This member is an explicit interface member implementation. It can be used only method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. Use the property to determine whether the current instance supports writing. If the operation is canceled before it completes, the returned task contains the value for the property. - For an example, see the overload. + For an example, see the overload. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index 9bf8eabaacc..945483c1535 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -94,13 +94,13 @@ is designed for character input in a particular encoding, whereas the class is designed for byte input and output. Use for reading lines of information from a standard text file. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. + defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. - The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. + The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -115,7 +115,7 @@ :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/readtextfile.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Overview/readtextfile.vb" id="Snippet1"::: - The following example instantiates a object and calls its method to read a file asynchronously. + The following example instantiates a object and calls its method to read a file asynchronously. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/asyncex1.cs" id="Snippet51"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Overview/asyncex1.vb" id="Snippet51"::: @@ -196,7 +196,7 @@ ## Remarks This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -366,9 +366,9 @@ ## Remarks This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -453,9 +453,9 @@ object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The character encoding is set by the `encoding` parameter, and the buffer size is set to 1024 bytes. The object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -545,7 +545,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -693,7 +693,7 @@ object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor initializes the encoding as specified by the `encoding` parameter, and the internal buffer size to 1024 bytes. The object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -794,9 +794,9 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter, the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -892,7 +892,7 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -995,9 +995,9 @@ ## Remarks The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used. - This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -1099,7 +1099,7 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter. - This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used. @@ -1273,11 +1273,11 @@ object calls on the provided object when is called. + Unless you set the `leaveOpen` parameter to `true`, the object calls on the provided object when is called. The buffer size, in bytes, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 bytes), the minimum allowable size is used. - This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -1341,7 +1341,7 @@ class buffers input from the underlying stream when you call one of the methods. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. The constructors that have the `detectEncodingFromByteOrderMarks` parameter can change the encoding the first time you read from the object. + You use this property to access the underlying stream. The class buffers input from the underlying stream when you call one of the methods. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. The constructors that have the `detectEncodingFromByteOrderMarks` parameter can change the encoding the first time you read from the object. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1402,11 +1402,11 @@ ## Remarks -This method overrides the method. +This method overrides the method. -This implementation of calls the method, passing a `true` value. +This implementation of calls the method, passing a `true` value. -Following a call to , any operations on the reader might raise exceptions. +Following a call to , any operations on the reader might raise exceptions. ]]> @@ -1536,14 +1536,14 @@ Following a call to , any operations on th method to reset the internal buffer for the object. You need to call this method only when the position of the internal buffer and the do not match. These positions can become mismatched when you read data into the buffer and then seek a new position in the underlying stream. This method slows performance and should be used only when absolutely necessary, such as when you want to read a portion of the contents of a object more than once. + Use the method to reset the internal buffer for the object. You need to call this method only when the position of the internal buffer and the do not match. These positions can become mismatched when you read data into the buffer and then seek a new position in the underlying stream. This method slows performance and should be used only when absolutely necessary, such as when you want to read a portion of the contents of a object more than once. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - The following example shows a scenario where the method must be called to synchronize the internal buffer and the underlying stream. The file in the example is used to illustrate position and consists of the text `abcdefghijklmnopqrstuvwxyz`. By calling after the data is read, the example works as expected. After the first 15 characters are read, the position is reset to the offset value of 2 and all the remaining characters are read. If you remove the call to , the example does not work as expected. The first 15 characters are read, but only the position of the underlying stream is reset. The internal buffer of the object is still on the 16th character. Therefore, returns all the characters in the buffer plus the characters in the underlying stream starting from the reset position. + The following example shows a scenario where the method must be called to synchronize the internal buffer and the underlying stream. The file in the example is used to illustrate position and consists of the text `abcdefghijklmnopqrstuvwxyz`. By calling after the data is read, the example works as expected. After the first 15 characters are read, the position is reset to the offset value of 2 and all the remaining characters are read. If you remove the call to , the example does not work as expected. The first 15 characters are read, but only the position of the underlying stream is reset. The internal buffer of the object is still on the 16th character. Therefore, returns all the characters in the buffer plus the characters in the underlying stream starting from the reset position. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/program.cs" id="Snippet30"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Overview/module1.vb" id="Snippet30"::: @@ -1611,9 +1611,9 @@ Following a call to , any operations on th method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that the object references. This method invokes the method of each referenced object. + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that the object references. This method invokes the method of each referenced object. . @@ -1738,7 +1738,7 @@ Following a call to , any operations on th , zero is always returned. When is invoked on , `null` is returned. + When read methods are invoked on , zero is always returned. When is invoked on , `null` is returned. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1808,11 +1808,11 @@ Following a call to , any operations on th method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. + The method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - This method overrides . + This method overrides . - The current position of the object is not changed by . + The current position of the object is not changed by . @@ -1900,16 +1900,16 @@ Following a call to , any operations on th . + This method overrides . - This method returns an integer so that it can return -1 if the end of the stream has been reached. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + This method returns an integer so that it can return -1 if the end of the stream has been reached. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - The following code example demonstrates a simple use of the method. + The following code example demonstrates a simple use of the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Read/strmreader read1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Read/strmreader read1.vb" id="Snippet1"::: @@ -2043,13 +2043,13 @@ Following a call to , any operations on th . + This method overrides . This method returns an integer so that it can return 0 if the end of the stream has been reached. - When using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream, where the internal buffer is set to your desired block size, and to always read less than the block size. If the size of the internal buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + When using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream, where the internal buffer is set to your desired block size, and to always read less than the block size. If the size of the internal buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. - This method returns after either the number of characters specified by the `count` parameter are read, or the end of the file is reached. is a blocking version of . + This method returns after either the number of characters specified by the `count` parameter are read, or the end of the file is reached. is a blocking version of . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2191,7 +2191,7 @@ Following a call to , any operations on th This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. + The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example42.cs" id="Snippet42"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Overview/example42.vb" id="Snippet42"::: @@ -2318,7 +2318,7 @@ Following a call to , any operations on th ## Remarks The position of the underlying stream is advanced by the number of characters that were read into `buffer`. - The method blocks until either `count` characters are read, or the end of the stream has been reached. This is a blocking version of . + The method blocks until either `count` characters are read, or the end of the stream has been reached. This is a blocking version of . ]]> @@ -2520,9 +2520,9 @@ Following a call to , any operations on th ## Remarks A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), or a carriage return immediately followed by a line feed ("\r\n"). The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end of the input stream is reached. - This method overrides . + This method overrides . - If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2737,15 +2737,15 @@ This method stores in the task it returns all non-usage exceptions that the meth . + This method overrides . - works best when you need to read all the input from the current position to the end of the stream. If more control is needed over how many characters are read from the stream, use the method overload, which generally results in better performance. + works best when you need to read all the input from the current position to the end of the stream. If more control is needed over how many characters are read from the stream, use the method overload, which generally results in better performance. - assumes that the stream knows when it has reached an end. For interactive protocols in which the server sends data only when you ask for it and does not close the connection, might block indefinitely because it does not reach an end, and should be avoided. + assumes that the stream knows when it has reached an end. For interactive protocols in which the server sends data only when you ask for it and does not close the connection, might block indefinitely because it does not reach an end, and should be avoided. - Note that when using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream. If the size of the buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). + Note that when using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream. If the size of the buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). - If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index a212ca58ba7..22851780c9e 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -94,18 +94,18 @@ is designed for character output in a particular encoding, whereas classes derived from are designed for byte input and output. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . + defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - The following example shows how to use a object to write a file that lists the directories on the C drive, and then uses a object to read and display each directory name. A good practice is to use these objects in a `using` statement so that the unmanaged resources are correctly disposed. The `using` statement automatically calls on the object when the code that is using it has completed. The constructor used in this example is not supported for use in Windows Store Apps. + The following example shows how to use a object to write a file that lists the directories on the C drive, and then uses a object to read and display each directory name. A good practice is to use these objects in a `using` statement so that the unmanaged resources are correctly disposed. The `using` statement automatically calls on the object when the code that is using it has completed. The constructor used in this example is not supported for use in Windows Store Apps. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/Overview/module1.vb" id="Snippet1"::: @@ -191,9 +191,9 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. @@ -274,7 +274,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created. @@ -382,9 +382,9 @@ property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . + This constructor initializes the property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -469,7 +469,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -627,9 +627,9 @@ property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . + This constructor initializes the property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -726,7 +726,7 @@ property using the encoding parameter. For additional information, see . + This constructor initializes the property using the encoding parameter. For additional information, see . `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -891,7 +891,7 @@ object calls on the provided object when is called. + Unless you set the `leaveOpen` parameter to `true`, the object calls on the provided object when is called. This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. @@ -986,7 +986,7 @@ property using the encoding parameter. For additional information, see . + This constructor initializes the property using the encoding parameter. For additional information, see . `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -1082,11 +1082,11 @@ or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. When `AutoFlush` is set to `false`, `StreamWriter` will do a limited amount of buffering, both internally and potentially in the encoder from the encoding you passed in. You can get better performance by setting `AutoFlush` to `false`, assuming that you always call `Close` (or at least `Flush`) when you're done writing with a `StreamWriter`. - For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . + For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1215,13 +1215,13 @@ . + This method overrides . - This implementation of calls the method passing a `true` value. + This implementation of calls the method passing a `true` value. - You must call to ensure that all data is correctly written out to the underlying stream. Following a call to , any operations on the might raise exceptions. If there is insufficient space on the disk, calling will raise an exception. + You must call to ensure that all data is correctly written out to the underlying stream. Following a call to , any operations on the might raise exceptions. If there is insufficient space on the disk, calling will raise an exception. - Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. @@ -1520,9 +1520,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo . + This method overrides . - Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1773,9 +1773,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo . + This method overrides . - The specified character is written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. + The specified character is written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1853,9 +1853,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo . + This method overrides . - The specified characters are written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. + The specified characters are written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. This method might provide faster performance than `Write` (`char[],``int,``int`) because it has fewer arguments to check. @@ -1980,11 +1980,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo . + This method overrides . The specified is written to the underlying stream unless the end of the stream is reached prematurely. - is invoked automatically if is `true`. If `value` is `null`, no entries are written. + is invoked automatically if is `true`. If `value` is `null`, no entries are written. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2267,9 +2267,9 @@ See for a descr . + This method overrides . - The characters are read from `buffer` beginning at `index` and continuing through `index` + (`count` - 1). All characters are written to the underlying stream unless the end of the underlying stream is reached prematurely. is invoked automatically if is `true`. + The characters are read from `buffer` beginning at `index` and continuing through `index` + (`count` - 1). All characters are written to the underlying stream unless the end of the underlying stream is reached prematurely. is invoked automatically if is `true`. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2509,7 +2509,7 @@ See , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write a single character (the letter "a") to a text file by using the method. + The following example shows how to write a single character (the letter "a") to a text file by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example20.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example20.vb" id="Snippet20"::: @@ -2592,7 +2592,7 @@ This method stores in the task it returns all non-usage exceptions that the meth This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write a string to a text file by using the method. + The following example shows how to write a string to a text file by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example21.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example21.vb" id="Snippet21"::: @@ -2725,7 +2725,7 @@ This method stores in the task it returns all non-usage exceptions that the meth This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write multiple characters to a text file by using the method. + The following example shows how to write multiple characters to a text file by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example24.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example24.vb" id="Snippet24"::: @@ -2788,7 +2788,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks -The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan%601.ToString%2A) method. +The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan`1.ToString%2A) method. The line terminator is defined by the field. @@ -2846,11 +2846,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This overload is equivalent to the overload. +This overload is equivalent to the overload. The line terminator is defined by the field. -This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . +This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3337,7 +3337,7 @@ See method. + The following example shows how to write a single character (the letter "a") to a line in a text file, followed by another line that contains a single character (the letter "b"), by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example22.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example22.vb" id="Snippet22"::: @@ -3421,7 +3421,7 @@ See , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write two lines that consist of string values to a text file by using the method. + The following example shows how to write two lines that consist of string values to a text file by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example23.cs" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example23.vb" id="Snippet23"::: @@ -3563,7 +3563,7 @@ The line terminator is defined by the fi ## Examples - The following example shows how to write characters to two separate lines in a text file by using the method. The first line contains the first 11 characters from the string (the letters "First line" followed by a space). The second line contains the remaining characters from the string (the letters "and second line"). + The following example shows how to write characters to two separate lines in a text file by using the method. The first line contains the first 11 characters from the string (the letters "First line" followed by a space). The second line contains the remaining characters from the string (the letters "and second line"). :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example25.cs" id="Snippet25"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example25.vb" id="Snippet25"::: diff --git a/xml/System.IO/StringReader.xml b/xml/System.IO/StringReader.xml index 29fb69c105f..05691d24a18 100644 --- a/xml/System.IO/StringReader.xml +++ b/xml/System.IO/StringReader.xml @@ -91,7 +91,7 @@ enables you to read a string synchronously or asynchronously. You can read a character at a time with the or the method, a line at a time using the or the method and an entire string using the or the method. + enables you to read a string synchronously or asynchronously. You can read a character at a time with the or the method, a line at a time using the or the method and an entire string using the or the method. [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] @@ -102,11 +102,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -192,11 +192,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -204,7 +204,7 @@ ## Examples This code example is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.IO/StringReader/.ctor/stringrw.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringReader/.ctor/stringrw.vb" id="Snippet2"::: @@ -268,9 +268,9 @@ For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). -This method overrides the method. +This method overrides the method. -This implementation of `Close` calls the , method passing a `true` value. Following a call to `Close`, other methods might throw an exception. +This implementation of `Close` calls the , method passing a `true` value. Following a call to `Close`, other methods might throw an exception. ]]> @@ -407,9 +407,9 @@ This implementation of `Close` calls the method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. + The method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - This method overrides the method. + This method overrides the method. The current position of the `StringReader` is not changed by this operation. @@ -420,7 +420,7 @@ This implementation of `Close` calls the | +|Get the size of a file.|| ]]> @@ -500,7 +500,7 @@ This implementation of `Close` calls the method. + This method overrides the method. The following table lists examples of other typical or related I/O tasks. @@ -509,11 +509,11 @@ This implementation of `Close` calls the


| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -641,7 +641,7 @@ This implementation of `Close` calls the . + This method overrides . The method will read up to `count` characters from the into the `buffer` character array starting at position `index`. Returns the actual number of characters read, or zero if the end of the string has been reached and no characters are read. @@ -652,11 +652,11 @@ This implementation of `Close` calls the


| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1054,11 +1054,11 @@ This implementation of `Close` calls the method. + This method overrides the method. A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), a carriage return immediately followed by a line feed ("\r\n"), or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end-of-stream marker has been reached. That is to say, if there is nothing between the last line read and the end-of-stream marker, the method returns `null`. - If the current method throws an , the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the . To avoid such a situation, use the method and store the read characters in a preallocated buffer. + If the current method throws an , the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the . To avoid such a situation, use the method and store the read characters in a preallocated buffer. The following table lists examples of other typical or related I/O tasks. @@ -1067,11 +1067,11 @@ This implementation of `Close` calls the


| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1270,9 +1270,9 @@ This method stores in the task it returns all non-usage exceptions that the meth method. + This method overrides the method. - If the current method throws an , the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the . To avoid such a situation, use the method and store the read characters in a preallocated buffer. + If the current method throws an , the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the . To avoid such a situation, use the method and store the read characters in a preallocated buffer. The following table lists examples of other typical or related I/O tasks. @@ -1281,11 +1281,11 @@ This method stores in the task it returns all non-usage exceptions that the meth |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| diff --git a/xml/System.IO/StringWriter.xml b/xml/System.IO/StringWriter.xml index ee1ded5af89..160214180f1 100644 --- a/xml/System.IO/StringWriter.xml +++ b/xml/System.IO/StringWriter.xml @@ -91,7 +91,7 @@ enables you to write to a string synchronously or asynchronously. You can write a character at a time with the or the method, a string at a time using the or the method. In addition, you can write a character, an array of characters or a string followed by the line terminator asynchronously with one of the methods. + enables you to write to a string synchronously or asynchronously. You can write a character at a time with the or the method, a string at a time using the or the method. In addition, you can write a character, an array of characters or a string followed by the line terminator asynchronously with one of the methods. [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] @@ -102,11 +102,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -192,7 +192,7 @@ object is automatically created and associated with the new instance of the class. Since a format control is not specified for this constructor, the new instance will be initialized with . + A new object is automatically created and associated with the new instance of the class. Since a format control is not specified for this constructor, the new instance will be initialized with . The following table lists examples of other typical or related I/O tasks. @@ -201,11 +201,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -292,11 +292,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -373,7 +373,7 @@ . + Since a format control is not specified for this constructor, the new instance will be initialized with . The following table lists examples of other typical or related I/O tasks. @@ -382,11 +382,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -476,11 +476,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -550,16 +550,16 @@ ## Remarks For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). - This method overrides . + This method overrides . - This implementation of `Close` calls the method passing a `true` value. + This implementation of `Close` calls the method passing a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call `Close`. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/.ctor/strwriter3.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/.ctor/strwriter3.vb" id="Snippet2"::: @@ -933,7 +933,7 @@ ## Examples - This code example is part of a larger example provided for the constructor. + This code example is part of a larger example provided for the constructor. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/.ctor/strwriter2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/.ctor/strwriter2.vb" id="Snippet2"::: @@ -1017,7 +1017,7 @@ . + This method overrides . The following table lists examples of other typical or related I/O tasks. @@ -1026,11 +1026,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1157,7 +1157,7 @@ . + This method overrides . If the specified string is `null`, nothing is written. @@ -1168,11 +1168,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1295,7 +1295,7 @@ . + This method overrides . This method writes `count` characters of data to this `StringWriter` from `buffer`, starting at position `index`. @@ -1306,11 +1306,11 @@ |Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| |Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](/dotnet/standard/io/how-to-open-and-append-to-a-log-file)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file)| @@ -1410,7 +1410,7 @@ This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write characters by using the method. + The following example shows how to write characters by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example5.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example5.vb" id="Snippet5"::: @@ -1493,7 +1493,7 @@ This method stores in the task it returns all non-usage exceptions that the meth This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write a string by using the method. + The following example shows how to write a string by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example4.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example4.vb" id="Snippet4"::: @@ -1680,7 +1680,7 @@ This method stores in the task it returns all non-usage exceptions that the meth This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ## Examples - The following example shows how to write characters by using the method. + The following example shows how to write characters by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example6.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example6.vb" id="Snippet6"::: @@ -1861,7 +1861,7 @@ The line terminator is defined by the proper ## Examples -The following example shows how to write characters by using the method. +The following example shows how to write characters by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example2.vb" id="Snippet2"::: @@ -1945,7 +1945,7 @@ The line terminator is defined by the proper ## Examples -The following example shows how to write a string by using the method. +The following example shows how to write a string by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example.vb" id="Snippet1"::: @@ -2132,7 +2132,7 @@ The line terminator is defined by the proper ## Examples -The following example shows how to write characters by using the method. +The following example shows how to write characters by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StringWriter/WriteAsync/example3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringWriter/WriteAsync/example3.vb" id="Snippet3"::: diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index ddec35f6903..b730cb11c72 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -104,12 +104,10 @@ is the abstract base class of and , which read characters from streams and strings, respectively. Use these derived classes to open a text file for reading a specified range of characters, or to create a reader based on an existing stream. > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. ## Examples - The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. + The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example42.cs" id="Snippet42"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamReader/Overview/example42.vb" id="Snippet42"::: @@ -235,10 +233,10 @@ method and passes it a `true` value. + This implementation of `Close` calls the method and passes it a `true` value. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -314,12 +312,12 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> @@ -451,13 +449,13 @@ ## Remarks Reading from the text reader is similar to reading from the end of a stream: -- The and methods return -1. +- The and methods return -1. -- The method returns zero. +- The method returns zero. -- The method returns `null`. +- The method returns `null`. -- The method returns an empty string. +- The method returns an empty string. ]]> @@ -521,11 +519,11 @@ method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. + The method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. The current position of the is not changed by this operation. The returned value is -1 if no more characters are available. The default implementation returns -1. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -602,7 +600,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -725,9 +723,9 @@ is a blocking version of this method. + This method returns after either `count` characters are read or the end of the file is reached. is a blocking version of this method. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -859,7 +857,7 @@ ## Remarks The task completes after either the number of characters specified by the `count` parameter are read or the end of the file is reached. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -992,7 +990,7 @@ ## Remarks The position of the underlying text reader is advanced by the number of characters that were read into `buffer`. - The method blocks until either `count` characters are read, or all characters have been read. This is a blocking version of . + The method blocks until either `count` characters are read, or all characters have been read. This is a blocking version of . ]]> @@ -1195,13 +1193,13 @@ , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. + A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), a carriage return followed by a line feed, , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. - If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. + If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. - To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. + To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -1274,9 +1272,9 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. + If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1412,11 +1410,11 @@ This method stores in the task it returns all non-usage exceptions that the meth exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the . If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. + If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the . If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. - To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. + To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -1492,7 +1490,7 @@ This method stores in the task it returns all non-usage exceptions that the meth class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index b71307a1658..5b7395a4e80 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -113,15 +113,15 @@ All the `Write` methods of having primitive data types as parameters write out the values as strings. - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). ## Examples - The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for writing to a stream. The following example shows how to write two lines that consist of string values to a text file by using the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for writing to a stream. The following example shows how to write two lines that consist of string values to a text file by using the method. :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example23.cs" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StreamWriter/AutoFlush/example23.vb" id="Snippet23"::: @@ -267,7 +267,7 @@ property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. + Use this constructor overload to provide a value for the property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -330,12 +330,12 @@ method and passes it a `true` value. + This implementation of `Close` calls the method and passes it a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -523,11 +523,11 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - **Note** Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. + **Note** Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> @@ -589,7 +589,7 @@ . By default, this method specifies the `disposing` parameter as `true`. `Finalize` specifies the `disposing` parameter as `false`. + This method is called by `Dispose` and . By default, this method specifies the `disposing` parameter as `true`. `Finalize` specifies the `disposing` parameter as `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -771,7 +771,7 @@ ## Remarks This default method does nothing, but derived classes can override the method to provide the appropriate functionality. - Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. ]]> @@ -937,7 +937,7 @@ property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. + The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). @@ -1079,7 +1079,7 @@ For non-Unix platforms, the default line terminator string is a carriage return ## Remarks Use `Null` to redirect output to a stream that will not consume any operating system resources. - When the methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. + When the methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1273,7 +1273,7 @@ This member is an explicit interface member implementation. It can be used only method. + The text representation of the specified value is produced by calling the method. This method outputs either or . @@ -1420,9 +1420,9 @@ This member is an explicit interface member implementation. It can be used only . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - This default method calls the method and passes the entire character array. If the character array is `null`, nothing is written. + This default method calls the method and passes the entire character array. If the character array is `null`, nothing is written. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1560,7 +1560,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1631,7 +1631,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1702,7 +1702,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1773,7 +1773,7 @@ This member is an explicit interface member implementation. It can be used only overload. + This overload is equivalent to the overload. If the specified object is `null`, no action is taken and no exception is thrown. Otherwise, the object's `ToString` method is called to produce the string representation, and the resulting string is then written to the output stream. The property, if not `null`, specifies the culture-specific formatting. @@ -1838,7 +1838,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan%601.ToString%2A) method. +The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan`1.ToString%2A) method. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1901,7 +1901,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1973,9 +1973,9 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo overload. + This overload is equivalent to the overload. - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If `value` is `null`, nothing is written to the text stream. @@ -2074,7 +2074,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method to avoid creating the intermediate string. +This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method to avoid creating the intermediate string. ]]> @@ -2141,7 +2141,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2218,7 +2218,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2329,11 +2329,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -2459,11 +2459,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -2612,7 +2612,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the ## Remarks This method will write `count` characters of data into this `TextWriter` from the `buffer` character array starting at position `index`. - This overload is equivalent to the overload for each character in `buffer` between `index` and (`index` + `count`). + This overload is equivalent to the overload for each character in `buffer` between `index` and (`index` + `count`). For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2725,11 +2725,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -2851,11 +2851,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -2952,7 +2952,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3103,7 +3103,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3380,7 +3380,7 @@ This method stores in the task it returns all non-usage exceptions that the meth class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3531,7 +3531,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. + The text representation of the specified value is produced by calling the method. This method outputs either or . @@ -3605,7 +3605,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo followed by . + This overload is equivalent to followed by . The line terminator is defined by the field. @@ -3680,7 +3680,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks All the characters in `buffer` are written to the underlying stream. If the character array is `null`, only the line terminator is written. - This overload is equivalent to followed by . + This overload is equivalent to followed by . The line terminator is defined by the field. @@ -3894,7 +3894,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -3967,7 +3967,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4042,7 +4042,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This overload is equivalent to the overload. The property, if not `null`, specifies the culture-specific formatting. +This overload is equivalent to the overload. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4107,7 +4107,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan%601.ToString%2A) method. +The text representation of the specified value is produced by calling the [ReadOnlySpan\.ToString](xref:System.ReadOnlySpan`1.ToString%2A) method. The line terminator is defined by the field. @@ -4252,11 +4252,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This overload is equivalent to the overload. +This overload is equivalent to the overload. The line terminator is defined by the field. -This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . +This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -4353,7 +4353,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -The text representation of the specified value is produced by calling the method. +The text representation of the specified value is produced by calling the method. The line terminator is defined by the field. @@ -4424,7 +4424,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4503,7 +4503,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4616,11 +4616,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -4748,11 +4748,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -4902,7 +4902,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks This method will write `count` characters of data into this `TextWriter` from the `buffer` character array starting at position `index`. - This overload is equivalent to calling the method followed by for each character in `buffer` between `index` and (`index` + `count`). + This overload is equivalent to calling the method followed by for each character in `buffer` between `index` and (`index` + `count`). The line terminator is defined by the field. @@ -5017,11 +5017,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -5145,11 +5145,11 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo |-------------|-----------------| |index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -5191,7 +5191,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. +The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -5328,7 +5328,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks The line terminator is defined by the field. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -5490,7 +5490,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks The line terminator is defined by the field. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.IO/UnmanagedMemoryAccessor.xml b/xml/System.IO/UnmanagedMemoryAccessor.xml index 22bc1f7fbc3..3c5369d8d5c 100644 --- a/xml/System.IO/UnmanagedMemoryAccessor.xml +++ b/xml/System.IO/UnmanagedMemoryAccessor.xml @@ -66,7 +66,7 @@ method of a object returns the unmanaged blocks of memory for working with views of memory-mapped files. + The method of a object returns the unmanaged blocks of memory for working with views of memory-mapped files. [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] @@ -2482,7 +2482,7 @@ methods in this class. + Use this method to write medium to large structures that are not easily accommodated by the other methods in this class. ]]> diff --git a/xml/System.IO/UnmanagedMemoryStream.xml b/xml/System.IO/UnmanagedMemoryStream.xml index 7d4ec2e0718..85cd555f326 100644 --- a/xml/System.IO/UnmanagedMemoryStream.xml +++ b/xml/System.IO/UnmanagedMemoryStream.xml @@ -361,7 +361,7 @@ The `capacity` parameter indicates the amount of total memory available. This value can describe a region that is longer than the length specified, or indicate a region that can be appended to. Any attempt to write beyond this value will fail. - The `access` parameter sets the , and properties. Note that specifying does not guarantee that the stream will be writable. The access parameters allow the implementer to create an object whose implementation can match the actual stream that is exposed. + The `access` parameter sets the , and properties. Note that specifying does not guarantee that the stream will be writable. The access parameters allow the implementer to create an object whose implementation can match the actual stream that is exposed. @@ -765,7 +765,7 @@ method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -895,7 +895,7 @@ calls the method, which means that no action performed. + If the operation isn't cancelled, the calls the method, which means that no action performed. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -982,7 +982,7 @@ ## Remarks -This method is equivalent to the constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, , initialize the pointer, and then invoke the method. +This method is equivalent to the constructor. It supports methods that need to initialize the pointer before setting stream variables and, therefore, cannot call the parameterized constructor. Such methods should use the parameterless constructor, , initialize the pointer, and then invoke the method. ]]> @@ -1194,7 +1194,7 @@ This method is equivalent to the and methods. will return 0 and will throw a . This support is primarily for design and code compatibility with basic stream operations. + Although you can set the position of the stream beyond the stream's capacity, you will not be able to access that area using the and methods. will return 0 and will throw a . This support is primarily for design and code compatibility with basic stream operations. ]]> @@ -1395,7 +1395,7 @@ This method is equivalent to the method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. + The method returns zero only after reaching the end of the stream. Otherwise, always reads at least one byte from the stream before returning. If no data is available from the stream upon a call to , the method will block until at least one byte of data can be returned. An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1534,7 +1534,7 @@ This method is equivalent to the of the property of the returned task. + If an exception occurs during the read operation, it will be set as the of the property of the returned task. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1675,7 +1675,7 @@ This method is equivalent to the . + For more information about seeking, see . ]]> @@ -1747,7 +1747,7 @@ This method is equivalent to the to work. + A stream must support both writing and seeking for to work. ]]> @@ -1960,7 +1960,7 @@ This method is equivalent to the of the property of the returned task. +If an exception occurs during the write operation, it will be set as the of the property of the returned task. ]]> @@ -2032,7 +2032,7 @@ If an exception occurs during the write operation, it will be set as the of the property of the returned task. + If an exception occurs during the write operation, it will be set as the of the property of the returned task. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.IO/WindowsRuntimeStreamExtensions.xml b/xml/System.IO/WindowsRuntimeStreamExtensions.xml index e4f22d58714..4b19c95b4a4 100644 --- a/xml/System.IO/WindowsRuntimeStreamExtensions.xml +++ b/xml/System.IO/WindowsRuntimeStreamExtensions.xml @@ -31,14 +31,14 @@ These extension methods are available only when you develop Windows Store apps. The `WindowsRuntimeStreamExtensions` class contains two methods for converting a managed object to a stream in the Windows Runtime: - - - - + - + - The `WindowsRuntimeStreamExtensions` class contains three overloaded methods for converting a stream in the Windows Runtime to a object: - - - - - - + - + - + - Starting with the .NET Framework 4.5.1, the `WindowsRuntimeStreamExtensions` class contains a method for converting a stream to a Windows Runtime : @@ -46,12 +46,12 @@ Starting with the .NET Framework 4.5.1, the `WindowsRuntimeStreamExtensions` cla ## Examples -The following example shows how to use the and +The following example shows how to use the and :::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.vb" id="Snippet2"::: -Here's the XAML code that is associated with the previous example. +Here's the XAML code that is associated with the previous example. :::code language="xaml" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml" id="Snippet1"::: ]]> @@ -90,13 +90,13 @@ Here's the XAML code that is associated with the previous example. [!NOTE] > In Visual Basic and C#, you can call this method as an instance method on any object of type . When you use instance method syntax to call this method, omit the first parameter. For more information, see [Extension Methods (Visual Basic)](/dotnet/visual-basic/programming-guide/language-features/procedures/extension-methods) or [Extension Methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods). ## Examples -The following example shows how to use the `AsInputStream` and methods to convert a managed stream to and from a stream in the Windows Runtime. +The following example shows how to use the `AsInputStream` and methods to convert a managed stream to and from a stream in the Windows Runtime. :::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage2.xaml.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage2.xaml.vb" id="Snippet4"::: @@ -150,7 +150,7 @@ Here's the XAML code that is associated with the previous example. ## Examples -The following example shows how to use the and `AsOutputStream`> methods to convert a managed stream to and from a stream in the Windows Runtime. +The following example shows how to use the and `AsOutputStream`> methods to convert a managed stream to and from a stream in the Windows Runtime. :::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage2.xaml.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage2.xaml.vb" id="Snippet4"::: @@ -340,7 +340,7 @@ A default buffer size of 16,384 bytes is used when converting the stream. To spe ## Examples -The following example shows how to use the and methods to convert a managed stream to and from a stream in the Windows Runtime. +The following example shows how to use the and methods to convert a managed stream to and from a stream in the Windows Runtime. :::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.vb" id="Snippet2"::: @@ -442,7 +442,7 @@ In most situations, buffering improves the performance of stream operations. You A default buffer size of 16,384 bytes is used when converting the stream. To specify a different buffer size, use the overload. ## Examples -The following example shows how to use the and methods to convert a managed stream to and from a stream in the Windows Runtime. +The following example shows how to use the and methods to convert a managed stream to and from a stream in the Windows Runtime. :::code language="csharp" source="~/snippets/csharp/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/WindowsRuntimeStreamExtensions/Overview/blankpage.xaml.vb" id="Snippet2"::: diff --git a/xml/System.Messaging/AccessControlEntry.xml b/xml/System.Messaging/AccessControlEntry.xml index 5e79af79155..335fa6d7846 100644 --- a/xml/System.Messaging/AccessControlEntry.xml +++ b/xml/System.Messaging/AccessControlEntry.xml @@ -23,7 +23,7 @@ ## Remarks Many applications have similar operations to which a trustee can be assigned rights, for example, reading, writing, and deleting objects. When you assign rights for these general operations, the application interprets them in a way specific to that application. For example, Message Queuing interprets the reading operation as receiving or peeking messages from a queue. The class provides access to these common rights. - When working with access control entries, you specify a trustee to which you are assigning the rights. You must set at least one of the , , or properties to indicate which rights to assign to the trustee. You can set the property to specify whether the rights you indicate should be granted or denied. The default entry type is to allow rights. + When working with access control entries, you specify a trustee to which you are assigning the rights. You must set at least one of the , , or properties to indicate which rights to assign to the trustee. You can set the property to specify whether the rights you indicate should be granted or denied. The default entry type is to allow rights. ]]> @@ -61,7 +61,7 @@ property and at least one of the , , or properties before using this instance to set access rights for a trustee. + Set the property and at least one of the , , or properties before using this instance to set access rights for a trustee. You can optionally set the property, though it defaults to `Allow` if you choose not to do so. @@ -93,7 +93,7 @@ property and at least one of the , , or properties before using this instance to set access rights for a trustee. + Set the property and at least one of the , , or properties before using this instance to set access rights for a trustee. ]]> diff --git a/xml/System.Messaging/ActiveXMessageFormatter.xml b/xml/System.Messaging/ActiveXMessageFormatter.xml index fd3664ad4f3..265bad31762 100644 --- a/xml/System.Messaging/ActiveXMessageFormatter.xml +++ b/xml/System.Messaging/ActiveXMessageFormatter.xml @@ -91,7 +91,7 @@ returns `false` if the message body is not a primitive that the Message Queuing ActiveX control can deserialize or if it does not implement the `IPersistStream` interface. + returns `false` if the message body is not a primitive that the Message Queuing ActiveX control can deserialize or if it does not implement the `IPersistStream` interface. ]]> diff --git a/xml/System.Messaging/BinaryMessageFormatter.xml b/xml/System.Messaging/BinaryMessageFormatter.xml index 16a994b027b..92864c62c9e 100644 --- a/xml/System.Messaging/BinaryMessageFormatter.xml +++ b/xml/System.Messaging/BinaryMessageFormatter.xml @@ -154,9 +154,9 @@ [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] - returns `false` if the message body is not a binary object. + returns `false` if the message body is not a binary object. - On the receiving computer, returns `true` if the assembly for the class to be deserialized exists locally. The assembly must be found in the global assembly cache, or be linked to the application (for example, if the object represents a custom class). + On the receiving computer, returns `true` if the assembly for the class to be deserialized exists locally. The assembly must be found in the global assembly cache, or be linked to the application (for example, if the object represents a custom class). ]]> @@ -369,7 +369,7 @@ Currently, you should accept the default value, `AssemblyStyle`. [!INCLUDE [untrusted-data-method-note](~/includes/untrusted-data-method-note.md)] - The top object format and type format need not be specified to write to the queue as they must be when reading. The and properties are used by the formatter only when deserializing a message. + The top object format and type format need not be specified to write to the queue as they must be when reading. The and properties are used by the formatter only when deserializing a message. The can serialize most objects, but the result is not loosely coupled. However, it is compact, so the formatter is efficient for large objects. diff --git a/xml/System.Messaging/Cursor.xml b/xml/System.Messaging/Cursor.xml index 63baac10c07..128048efa49 100644 --- a/xml/System.Messaging/Cursor.xml +++ b/xml/System.Messaging/Cursor.xml @@ -21,17 +21,17 @@ A is used to maintain a specific location in a when reading the queue's messages. - , call the method for that queue. - - A is used with such methods as and when you need to read messages that are not at the front of the queue. This includes reading messages synchronously or asynchronously. Cursors do not need to be used to read only the first message in a queue. - - When reading messages within a transaction, Message Queuing does not roll back cursor movement if the transaction is aborted. For example, suppose there is a queue with two messages, A1 and A2. If you remove message A1 while in a transaction, Message Queuing moves the cursor to message A2. However, if the transaction is aborted for any reason, message A1 is inserted back into the queue but the cursor remains pointing at message A2. - - To close the cursor, call . - + , call the method for that queue. + + A is used with such methods as and when you need to read messages that are not at the front of the queue. This includes reading messages synchronously or asynchronously. Cursors do not need to be used to read only the first message in a queue. + + When reading messages within a transaction, Message Queuing does not roll back cursor movement if the transaction is aborted. For example, suppose there is a queue with two messages, A1 and A2. If you remove message A1 while in a transaction, Message Queuing moves the cursor to message A2. However, if the transaction is aborted for any reason, message A1 is inserted back into the queue but the cursor remains pointing at message A2. + + To close the cursor, call . + ]]> diff --git a/xml/System.Messaging/DefaultPropertiesToSend.xml b/xml/System.Messaging/DefaultPropertiesToSend.xml index 256f903e117..9feb6e6d4e3 100644 --- a/xml/System.Messaging/DefaultPropertiesToSend.xml +++ b/xml/System.Messaging/DefaultPropertiesToSend.xml @@ -27,9 +27,9 @@ . is used to specify default property values of the message being sent when objects other than instances are sent to a queue, for example, the string argument passed into the method in the code fragment, `myMessageQueue.Send("hello")`. The class has corresponding, identically named properties to those in that provide the values when sending a instance specifically. Even if you have specified for a queue, sending a object to that queue will cause the values for the identically named properties to override the queue's values. + You can set default values on selected properties for messages sent to a . is used to specify default property values of the message being sent when objects other than instances are sent to a queue, for example, the string argument passed into the method in the code fragment, `myMessageQueue.Send("hello")`. The class has corresponding, identically named properties to those in that provide the values when sending a instance specifically. Even if you have specified for a queue, sending a object to that queue will cause the values for the identically named properties to override the queue's values. - Properties that you do not set explicitly default to the values specified by the constructor, . + Properties that you do not set explicitly default to the values specified by the constructor, . For a list of initial property values for an instance of , see the constructor. @@ -68,7 +68,7 @@ to define default property values to associate with objects sent to a queue that are not of type . When working with objects, a instance is created for you and associated with the member of the . + You can create a new instance of to define default property values to associate with objects sent to a queue that are not of type . When working with objects, a instance is created for you and associated with the member of the . There are two ways to define a queue's default properties to send, as shown in the following C# code. You can set values for this instance of and associate it with the queue's property: @@ -91,31 +91,31 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; myMessageQueue.Send("hello"); ``` - If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. + If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. The following table shows initial property values for an instance of . |Property|Initial value| |--------------|-------------------| -||`AcknowledgeTypes.None`| -||`null`| -||0| -||`true`| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||`HashAlgorithm.MD5`| -||An empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`AcknowledgeTypes.None`| +||`null`| +||0| +||`true`| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||`HashAlgorithm.MD5`| +||An empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| ]]> @@ -249,11 +249,11 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property contains additional, application-specific information that can be used to organize different types of messages, for example, using application-specific indexes. It is the responsibility of the application to interpret information. + The property contains additional, application-specific information that can be used to organize different types of messages, for example, using application-specific indexes. It is the responsibility of the application to interpret information. Where possible, message data should be included in the body of the message rather than in the property. - When working with foreign queues, use the property to specify non-Message Queuing message properties. As with , it is the responsibility of the application to understand the content of the property. + When working with foreign queues, use the property to specify non-Message Queuing message properties. As with , it is the responsibility of the application to understand the content of the property. ]]> @@ -298,7 +298,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; ## Remarks The sender ID is an array of bytes that represents the identifier of the sending user. The sender ID is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. The sender ID is only trustworthy if the message was authenticated when it reached the destination queue. - When the sender ID is not attached to the message, the sending application is indicating that Message Queuing should not validate the message's sender when the message is sent to the destination queue. If the destination queue only accepts authenticated messages, and either or is `false`, the message will be rejected when it reaches the queue. + When the sender ID is not attached to the message, the sending application is indicating that Message Queuing should not validate the message's sender when the message is sent to the destination queue. If the destination queue only accepts authenticated messages, and either or is `false`, the message will be rejected when it reaches the queue. ]]> @@ -398,7 +398,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property provides for additional application-defined information that is associated with the message, such as a large binary object. It is the responsibility of the receiving application to interpret the contents of the . + The property provides for additional application-defined information that is associated with the message, such as a large binary object. It is the responsibility of the receiving application to interpret the contents of the . Where possible, message data should be included in the body of the message rather than in the extension. @@ -587,9 +587,9 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; ## Remarks The property indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. - If delivery of a message is guaranteed, the message is stored locally at every step along the route until the message is successfully forwarded to the next computer. Setting to `true` on could affect the throughput. + If delivery of a message is guaranteed, the message is stored locally at every step along the route until the message is successfully forwarded to the next computer. Setting to `true` on could affect the throughput. - If the message is transactional, Message Queuing automatically treats the message as recoverable, regardless of whether is set to `true`. + If the message is transactional, Message Queuing automatically treats the message as recoverable, regardless of whether is set to `true`. ]]> @@ -677,14 +677,14 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; The property specifies the total time in seconds for a sent message to be received from the destination queue. This time limit includes the time spent getting to the destination queue, plus the time spent waiting in the queue before the message is retrieved by an application. > [!CAUTION] -> When using dependent client computers, synchronize the clock on the client computer with the clock on the server running Message Queuing. If the two clocks are not synchronized, you might see unpredictable behavior when sending messages when is not . +> When using dependent client computers, synchronize the clock on the client computer with the clock on the server running Message Queuing. If the two clocks are not synchronized, you might see unpredictable behavior when sending messages when is not . - If the interval expires before the message is removed from the queue, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is less than , takes precedence. + If the interval expires before the message is removed from the queue, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is less than , takes precedence. The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. > [!CAUTION] -> If you have specified to receive negative acknowledgments, you will not receive them when the value of is less than the value of . +> If you have specified to receive negative acknowledgments, you will not receive them when the value of is less than the value of . When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. @@ -729,11 +729,11 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; interval expires before the message reaches its destination, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is greater than , takes precedence. + If the interval expires before the message reaches its destination, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is greater than , takes precedence. The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. - If is 0 seconds, Message Queuing tries once to send the message to its destination if the queue is waiting for the message. If the queue is local, the message always reaches the queue. + If is 0 seconds, Message Queuing tries once to send the message to its destination if the queue is waiting for the message. If the queue is local, the message always reaches the queue. When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. @@ -828,7 +828,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; ## Remarks The property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and to authenticate the message when it is received. - If a message is sent to a queue that only accepts authenticated messages, the message will be rejected when it reaches the queue if is set to `false`. + If a message is sent to a queue that only accepts authenticated messages, the message will be rejected when it reaches the queue if is set to `false`. It is not possible to look at the properties of a message and determine whether a message failed authentication. Messages that fail authentication are discarded and are not delivered to the queue. @@ -875,7 +875,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; and specify how Message Queuing will track a message. If is `true`, then in case of delivery failure (for non-transactional messages), the message is sent to the non-transactional dead-letter queue on the computer that could not deliver the message (for example, if a message timer expires). + and specify how Message Queuing will track a message. If is `true`, then in case of delivery failure (for non-transactional messages), the message is sent to the non-transactional dead-letter queue on the computer that could not deliver the message (for example, if a message timer expires). In the case of delivery failure for transactional messages, the message is sent to the transactional dead-letter queue on the source computer in all negative and in-doubt cases. @@ -971,7 +971,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; and specify how Message Queuing will track a message. If is `true`, then at each step that a message is transmitted, a copy is kept in the computer journal on the originating computer. + and specify how Message Queuing will track a message. If is `true`, then at each step that a message is transmitted, a copy is kept in the computer journal on the originating computer. The sent message will only be copied to the journal queue if the destination queue is on a remote computer. If the destination is on the local computer, the message is sent directly to the queue; there are no intermediate steps to require journaling. @@ -979,7 +979,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; You do not create a journal or dead-letter queue. These are both system queues that are generated by Message Queuing. - Journaling can be specified by both the message and the queue. When is `true`, the message is journaled when it is sent. When is `true`, the message is journaled when it is received. + Journaling can be specified by both the message and the queue. When is `true`, the message is journaled when it is sent. When is `true`, the message is journaled when it is received. ]]> diff --git a/xml/System.Messaging/Message.xml b/xml/System.Messaging/Message.xml index 541617e0578..0da8a2a06b8 100644 --- a/xml/System.Messaging/Message.xml +++ b/xml/System.Messaging/Message.xml @@ -37,17 +37,17 @@ ## Remarks Use the class to peek or receive messages from a queue, or to have fine control over message properties when sending a message to a queue. - uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. + uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. - The class's method allows you to specify any object type for a message being sent to that queue. You can use the instance's property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a instance to send a message to the queue gives you the flexibility to access and modify many of these properties - either for a single message or on a message-by-message basis. properties take precedence over . + The class's method allows you to specify any object type for a message being sent to that queue. You can use the instance's property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a instance to send a message to the queue gives you the flexibility to access and modify many of these properties - either for a single message or on a message-by-message basis. properties take precedence over . - Message data is stored in the property and to a lesser extent, the and properties. When message data is encrypted, serialized, or deserialized, only the contents of the property are affected. + Message data is stored in the property and to a lesser extent, the and properties. When message data is encrypted, serialized, or deserialized, only the contents of the property are affected. - The contents of the property are serialized when the message is sent, using the property you specify. The serialized contents are found in the property. You can also set the property directly, for example, to send a file as the data content of a message. You can change the or properties at any time before sending the message, and the data will be serialized appropriately when you call . + The contents of the property are serialized when the message is sent, using the property you specify. The serialized contents are found in the property. You can also set the property directly, for example, to send a file as the data content of a message. You can change the or properties at any time before sending the message, and the data will be serialized appropriately when you call . The properties defined by the property apply only to messages that are not of type . If you specify the property for a , the identically named properties in a instance sent to that queue cause these default properties to be ignored. - For a list of initial property values for an instance of , see the constructor. + For a list of initial property values for an instance of , see the constructor. ## Examples The following code example demonstrates formatting a message body using . @@ -103,7 +103,7 @@ Specify either the property or the property before sending the object. The property can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. - Unless you write the contents of the message directly to the property, set the property before you send the message. The body is serialized using the property's value at the time the method is called on the instance. + Unless you write the contents of the message directly to the property, set the property before you send the message. The body is serialized using the property's value at the time the method is called on the instance. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -111,36 +111,36 @@ |Property|Initial value| |--------------|-------------------| -||`AcknowledgeType.None`| -||`null`| -||0| -||`true`| -||Microsoft Base Cryptographic Provider version 1.0| -||`CryptoProviderType.RSA_FULL`| -||`null`| -||`Stream.null`| -||0| -||`Guid.Empty`| -||An empty string ("")| -||A zero-length array of bytes| -||A zero-length array of bytes| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||`XmlMessageFormatter`| -||`HashAlgorithm.MD5`| -||An empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||A zero-length array of bytes| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`AcknowledgeType.None`| +||`null`| +||0| +||`true`| +||Microsoft Base Cryptographic Provider version 1.0| +||`CryptoProviderType.RSA_FULL`| +||`null`| +||`Stream.null`| +||0| +||`Guid.Empty`| +||An empty string ("")| +||A zero-length array of bytes| +||A zero-length array of bytes| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||`XmlMessageFormatter`| +||`HashAlgorithm.MD5`| +||An empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||A zero-length array of bytes| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| @@ -186,7 +186,7 @@ class that contains the specified by the `body` parameter. The `body` parameter can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. The body is serialized using the unless you change the property before the is sent. If you change the or property at any time before calling , the message will be serialized according to the new property value. + Use this overload to create a new instance of the class that contains the specified by the `body` parameter. The `body` parameter can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. The body is serialized using the unless you change the property before the is sent. If you change the or property at any time before calling , the message will be serialized according to the new property value. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -194,36 +194,36 @@ |Property|Initial value| |--------------|-------------------| -||`AcknowledgeType.None`| -||`null`| -||0| -||`true`| -||Microsoft Base Cryptographic Provider version 1.0| -||`CryptoProviderType.RSA_FULL`| -||The `body` parameter.| -||`Stream.null`| -||0| -||`Guid.Empty`| -||An empty string ("")| -||A zero-length array of bytes| -||A zero-length array of bytes| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||`XmlMessageFormatter`| -||`HashAlgorithm.MD5`| -||An empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||A zero-length array of bytes| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`AcknowledgeType.None`| +||`null`| +||0| +||`true`| +||Microsoft Base Cryptographic Provider version 1.0| +||`CryptoProviderType.RSA_FULL`| +||The `body` parameter.| +||`Stream.null`| +||0| +||`Guid.Empty`| +||An empty string ("")| +||A zero-length array of bytes| +||A zero-length array of bytes| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||`XmlMessageFormatter`| +||`HashAlgorithm.MD5`| +||An empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||A zero-length array of bytes| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| @@ -270,7 +270,7 @@ class that contains the specified by the `body` parameter and that uses any valid formatter to serialize the body. The `body` parameter is any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. If you change the or property at any time before calling , the message will be serialized according to the new property value. + Use this overload to create a new instance of the class that contains the specified by the `body` parameter and that uses any valid formatter to serialize the body. The `body` parameter is any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. If you change the or property at any time before calling , the message will be serialized according to the new property value. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -278,36 +278,36 @@ |Property|Initial value| |--------------|-------------------| -||`AcknowledgeType.None`| -||`null`| -||0| -||`true`| -||Microsoft Base Cryptographic Provider version 1.0| -||`CryptoProviderType.RSA_FULL`| -||The `body` parameter.| -||`Stream.null`| -||0| -||`Guid.Empty`| -||An empty string ("")| -||A zero-length array of bytes| -||A zero-length array of bytes| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||The `formatter` parameter.| -||`HashAlgorithm.MD5`| -||An empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||A zero-length array of bytes| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`AcknowledgeType.None`| +||`null`| +||0| +||`true`| +||Microsoft Base Cryptographic Provider version 1.0| +||`CryptoProviderType.RSA_FULL`| +||The `body` parameter.| +||`Stream.null`| +||0| +||`Guid.Empty`| +||An empty string ("")| +||A zero-length array of bytes| +||A zero-length array of bytes| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||The `formatter` parameter.| +||`HashAlgorithm.MD5`| +||An empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||A zero-length array of bytes| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| ## Examples @@ -366,7 +366,7 @@ ## Remarks The property specifies the type of acknowledgment messages requested by the sending application. Set the property before sending the message to request notification of certain occurrences - for example, a message reaching its destination queue, a message being retrieved, or a time-out preventing a message from reaching or being retrieved from the destination queue. - Message Queuing returns notification by sending acknowledgment messages to the property specified by the original message. An acknowledgment message's property indicates the type of acknowledgment that it represents. For example, if an acknowledgment message was sent because a message did not reach the destination before the interval expired, the property of the acknowledgment message would contain the value `ReachQueueTimeout`. + Message Queuing returns notification by sending acknowledgment messages to the property specified by the original message. An acknowledgment message's property indicates the type of acknowledgment that it represents. For example, if an acknowledgment message was sent because a message did not reach the destination before the interval expired, the property of the acknowledgment message would contain the value `ReachQueueTimeout`. @@ -649,10 +649,10 @@ ## Remarks The property is an array of bytes that represents the identifier of the sending user. The sender ID is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. - The absence of the sender ID is an indication by the sending application that Message Queuing should not validate the message's sender nor verify the sender's access rights to the receiving queue. The is trustworthy only if the message was authenticated when it reached the destination queue. The message is rejected when it reaches the destination queue if the queue accepts only authenticated messages and either the or the property is `false`. + The absence of the sender ID is an indication by the sending application that Message Queuing should not validate the message's sender nor verify the sender's access rights to the receiving queue. The is trustworthy only if the message was authenticated when it reached the destination queue. The message is rejected when it reaches the destination queue if the queue accepts only authenticated messages and either the or the property is `false`. > [!CAUTION] -> If a message is rejected, it is either sent to the dead-letter queue (if is `true`), or it is ignored. You can request acknowledgments when a message fails to reach a queue. Otherwise, when is `false` the message might be lost without warning. +> If a message is rejected, it is either sent to the dead-letter queue (if is `true`), or it is ignored. You can request acknowledgments when a message fails to reach a queue. Otherwise, when is `false` the message might be lost without warning. @@ -770,9 +770,9 @@ when working with foreign queues. Message Queuing requires the authentication provider name and authentication provider type of the cryptographic provider (authentication provider) to validate the digital signatures of both messages sent to a foreign queue and messages passed to Message Queuing from a foreign queue. + You typically use the when working with foreign queues. Message Queuing requires the authentication provider name and authentication provider type of the cryptographic provider (authentication provider) to validate the digital signatures of both messages sent to a foreign queue and messages passed to Message Queuing from a foreign queue. - When sending a message, always set the and properties together. When the message is sent, Message Queuing ignores the authentication provider name if the connector type is not also set. + When sending a message, always set the and properties together. When the message is sent, Message Queuing ignores the authentication provider name if the connector type is not also set. The property cannot be `null`, but it can be an empty string (""). @@ -833,7 +833,7 @@ Only `RsaFull` is intended to be used with messaging. - When sending a message, always set the and properties together. When the message is sent, Message Queuing ignores the authentication provider type if the connector type is not also set. + When sending a message, always set the and properties together. When the message is sent, Message Queuing ignores the authentication provider type if the connector type is not also set. ]]> @@ -884,9 +884,9 @@ property usually contains the data associated with the message. Although you can also send application-specific data in the and properties, you should include message data in the of the message whenever possible. Only the property contents are serialized or encrypted. + The message's property usually contains the data associated with the message. Although you can also send application-specific data in the and properties, you should include message data in the of the message whenever possible. Only the property contents are serialized or encrypted. - The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . + The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . The string argument in `MessageQueue.Send("hello.")` is an example of such a generic object. @@ -894,7 +894,7 @@ Specify either the property or the property before sending the object. The property can be any serializable object, such as a text string, structure object, class instance, or embedded object. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . > [!NOTE] > Attempting to set the body of a message to will cause a when the `Send` method of the class is called and the is used. @@ -979,7 +979,7 @@ Specify either the property or the property before sending the object. If you set the property, the contents are serialized into the property. However, you can choose to write the property directly. This is useful, for example, when you want to open a connection to a file and stream its contents as the body of your message. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . If you set the property to `true` for the body of this message, the message will be encrypted when it is sent, not when you set the property. Therefore, the property is never encrypted. @@ -1106,25 +1106,25 @@ if (myObject is float) { property be set whenever an application sets a message property that is usually set by Message Queuing. An application typically uses a in the following two cases: + Message Queuing requires the property be set whenever an application sets a message property that is usually set by Message Queuing. An application typically uses a in the following two cases: -- Whenever a connector application passes a message. The tells the sending and receiving applications how to interpret the security and acknowledgment properties of the message. +- Whenever a connector application passes a message. The tells the sending and receiving applications how to interpret the security and acknowledgment properties of the message. -- Whenever the sending application, rather than Message Queuing, encrypts a message. The tells Message Queuing to use the property value to decrypt the message. +- Whenever the sending application, rather than Message Queuing, encrypts a message. The tells Message Queuing to use the property value to decrypt the message. You must set the property if you set any of the following properties (otherwise, the queue ignores these properties when the message is sent): -- +- -- +- -- +- -- +- -- +- -- +- ]]> @@ -1514,7 +1514,7 @@ if (myObject is float) { ## Remarks Use the property when reading and writing a message. When a message is sent to the queue, the formatter serializes the property into a stream that can be sent to the message queue. When reading from a queue, the formatter deserializes the message data into the property. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -1678,7 +1678,7 @@ if (myObject is float) { and require a value that specifies a time-out. For the former, the time-out is the maximum time allowed for a message to be received from the queue. For the latter, the time-out is the time allowed for a message to reach the queue. In both cases, you can specify the time-out as a number of seconds or use to indicate that no time-out exists. + and require a value that specifies a time-out. For the former, the time-out is the maximum time allowed for a message to be received from the queue. For the latter, the time-out is the time allowed for a message to reach the queue. In both cases, you can specify the time-out as a number of seconds or use to indicate that no time-out exists. @@ -1732,9 +1732,9 @@ if (myObject is float) { This property is available only with Message Queuing version 2.0 and later. - To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the last message sent in the transaction, and use the latter to retrieve the identifier of the transaction. + To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the last message sent in the transaction, and use the latter to retrieve the identifier of the transaction. - If only one message is sent in a transaction, the and properties are both set to `true`. + If only one message is sent in a transaction, the and properties are both set to `true`. @@ -1794,9 +1794,9 @@ if (myObject is float) { This property is available only with Message Queuing version 2.0 and later. - To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the first message sent in the transaction, and use the latter to retrieve the identifier of the transaction. + To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the first message sent in the transaction, and use the latter to retrieve the identifier of the transaction. - If only one message is sent in a transaction, the and properties are both set to `true`. + If only one message is sent in a transaction, the and properties are both set to `true`. @@ -1903,7 +1903,7 @@ if (myObject is float) { The property can only be read on messages retrieved from a queue. - A lookup identifier is used to read a specific message in the queue. Once the lookup identifier of a message is known, the receiving application can call the or function to go directly to that message and peek at or retrieve it from the queue, unlike cursors that must start at the front of the queue and navigate towards the end of the queue, + A lookup identifier is used to read a specific message in the queue. Once the lookup identifier of a message is known, the receiving application can call the or function to go directly to that message and peek at or retrieve it from the queue, unlike cursors that must start at the front of the queue and navigate towards the end of the queue, Obtaining the lookup identifiers of the messages in the queue is the responsibility of the application. One possible way to obtain the lookup identifiers is to create a trigger for the destination queue that invokes a component that caches the identifiers of each message as they are placed in the queue. @@ -2444,7 +2444,7 @@ if (myObject is float) { property does not include preceding two forward slashes (\\\\). For example, `myServer` is a valid . + The format of the property does not include preceding two forward slashes (\\\\). For example, `myServer` is a valid . @@ -2511,11 +2511,11 @@ if (myObject is float) { > [!CAUTION] > When using dependent client computers, be sure the clock on the client computer is synchronized with the clock on the server that is running Message Queuing. Otherwise, unpredictable behavior might result when sending a message whose property is not . - If the interval specified by the property expires before the message is removed from the queue, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored. + If the interval specified by the property expires before the message is removed from the queue, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored. You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. - If the value specified by the property is less than the value specified by the property, takes precedence. + If the value specified by the property is less than the value specified by the property, takes precedence. When several messages are sent in a single transaction, Message Queuing uses the property of the first message. @@ -2576,13 +2576,13 @@ if (myObject is float) { property expires before the message reaches its destination, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored + If the interval specified by the property expires before the message reaches its destination, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. If the property is set to 0 seconds, Message Queuing tries once to send the message to its destination - if the queue is waiting for the message. If the queue is local, the message always reaches it. - If the value specified by the property is greater than the value specified by the property, takes precedence. + If the value specified by the property is greater than the value specified by the property, takes precedence. When several messages are sent in a single transaction, Message Queuing uses the property of the first message. @@ -2637,7 +2637,7 @@ if (myObject is float) { Transaction identifiers are not guaranteed to be unique, because transaction sequence numbers are not persistent, and they start over again at 2 20. Message Queuing guarantees only that subsequent transactions will have different transaction sequence numbers. - You can use the property along with the and properties to verify transaction boundaries. + You can use the property along with the and properties to verify transaction boundaries. @@ -2765,7 +2765,7 @@ if (myObject is float) { ## Remarks The property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and authenticate the message when it is received. - If is `false` and a message is sent to a queue that accepts only authenticated messages, the message will be rejected when it reaches the queue. + If is `false` and a message is sent to a queue that accepts only authenticated messages, the message will be rejected when it reaches the queue. You cannot determine if a message failed authentication by looking at its properties. Message Queuing discards such messages before they are delivered to the queue. However, you can request that an acknowledgment message be sent if a delivery failure prevents a message from arriving in the queue. @@ -2821,7 +2821,7 @@ if (myObject is float) { and properties specify how Message Queuing tracks a message. If is `true`, delivery failure (of a non-transactional message), causes the message to be sent to the non-transactional dead-letter queue on the computer that could not deliver the message. Delivery failure could be caused by a message timer expiring, for example. + The and properties specify how Message Queuing tracks a message. If is `true`, delivery failure (of a non-transactional message), causes the message to be sent to the non-transactional dead-letter queue on the computer that could not deliver the message. Delivery failure could be caused by a message timer expiring, for example. In the case of delivery failure for a transactional message, Message Queuing sends the message to the transactional dead-letter queue on the source machine in all negative and in-doubt cases. @@ -2939,7 +2939,7 @@ if (myObject is float) { and properties specify how Message Queuing tracks a message. If is `true`, then a copy is kept in the computer journal on the originating machine at each step that a message is transmitted. + The and properties specify how Message Queuing tracks a message. If is `true`, then a copy is kept in the computer journal on the originating machine at each step that a message is transmitted. The sent message is only copied to the journal queue if the destination queue is on a remote computer. If the destination is on the local computer, the message is sent directly to the queue; there are no intermediate steps to require journaling. diff --git a/xml/System.Messaging/MessageEnumerator.xml b/xml/System.Messaging/MessageEnumerator.xml index c205dbd2fa9..43d5cbacded 100644 --- a/xml/System.Messaging/MessageEnumerator.xml +++ b/xml/System.Messaging/MessageEnumerator.xml @@ -34,14 +34,14 @@ An enumerator does not remove the messages from the queue when it queries the queue. It returns information about the message at the current cursor position, but it leaves the message in the queue. - A is a cursor, initialized to the head of a dynamic list. The list order is the same as the order of the messages in the queue, according to message priority. You can move the cursor to the first message in the queue by calling . After the enumerator has been initialized, you can use to step forward through the remaining messages. You can specify whether to wait for a message to become available by passing a timeout into the method. + A is a cursor, initialized to the head of a dynamic list. The list order is the same as the order of the messages in the queue, according to message priority. You can move the cursor to the first message in the queue by calling . After the enumerator has been initialized, you can use to step forward through the remaining messages. You can specify whether to wait for a message to become available by passing a timeout into the method. - Because the enumerator is dynamic, a message that is appended beyond the cursor's current position (for example, due to low priority), can be accessed by the enumerator. A message that is inserted before the cursor's current position cannot be accessed. It is not possible to step backward with a . A cursor allows forward-only movement. The method enables you to place the cursor back at the beginning of the queue. + Because the enumerator is dynamic, a message that is appended beyond the cursor's current position (for example, due to low priority), can be accessed by the enumerator. A message that is inserted before the cursor's current position cannot be accessed. It is not possible to step backward with a . A cursor allows forward-only movement. The method enables you to place the cursor back at the beginning of the queue. Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. > [!NOTE] -> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. +> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. @@ -82,7 +82,7 @@ to release the resources associated with the handle. + The operating system retains an open handle to the queue during the lifetime of the cursor. When you have finished working with the enumerator, call to release the resources associated with the handle. ]]> @@ -113,7 +113,7 @@ is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first message in the queue. + When the enumerator is created, it points to the head of the queue, at a location before the first message. In this case, is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first message in the queue. ]]> @@ -152,7 +152,7 @@ to release this resource. + This property contains the native handle to the enumeration. When you have finished working with the enumerator, call to release this resource. ]]> @@ -196,7 +196,7 @@ allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> @@ -231,7 +231,7 @@ method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. @@ -270,7 +270,7 @@ . Application code should not call this method; an object's Finalize method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. +This method overrides . Application code should not call this method; an object's Finalize method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v=vs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -319,9 +319,9 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro ## Remarks This overload returns immediately if there is no message in the queue. There is another overload that waits a specified for a message to arrive. - If a message is not currently available because the queue is empty or because you have moved beyond the last element in the collection, returns `false` to the calling method. + If a message is not currently available because the queue is empty or because you have moved beyond the last element in the collection, returns `false` to the calling method. - Upon creation, an enumerator is conceptually positioned before the first message of the queue, and the first call to brings the first message of the queue into view. + Upon creation, an enumerator is conceptually positioned before the first message of the queue, and the first call to brings the first message of the queue into view. ]]> @@ -360,11 +360,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro waits the specified timeout. + This overload waits if there is no message in the queue or if the cursor has reached the end of the queue. If a message is not currently available because the queue is empty or because you have moved beyond the last element in the collection, waits the specified timeout. - If the cursor is already at the end of the queue, only returns `true` if the new message arrives within the specified time interval, has lower priority than all messages currently in the queue and is placed at the end of the queue. An overload with no parameter returns immediately if no further messages are in the queue. + If the cursor is already at the end of the queue, only returns `true` if the new message arrives within the specified time interval, has lower priority than all messages currently in the queue and is placed at the end of the queue. An overload with no parameter returns immediately if no further messages are in the queue. - Upon creation, an enumerator is conceptually positioned before the first message of the enumeration, and the first call to brings the first message of the enumeration into view. + Upon creation, an enumerator is conceptually positioned before the first message of the enumeration, and the first call to brings the first message of the enumeration into view. ]]> @@ -390,7 +390,7 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro instance is retrieved by using the . Do not use to retrieve an instance of as this method has been deprecated. + The behavior described for these overloads is applicable only if the instance is retrieved by using the . Do not use to retrieve an instance of as this method has been deprecated. ]]> @@ -421,11 +421,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location. + removes and returns the message at the cursor's current location. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. @@ -463,13 +463,13 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location, using the internal transaction context defined by the `transaction` parameter. + removes and returns the message at the cursor's current location, using the internal transaction context defined by the `transaction` parameter. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . ]]> @@ -507,15 +507,15 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. + removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . ]]> @@ -553,11 +553,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . If you call this overload on a transactional queue, Message Queuing creates a single internal transaction. @@ -599,13 +599,13 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + removes and returns the message at the cursor's current location. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . ]]> @@ -647,15 +647,15 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. + removes and returns the message at the cursor's current location, using a transaction context defined by the `transactionType` parameter. If the cursor is at the end of the queue, this overload of the method waits until a message is available or the interval specified by the `timeout` parameter has expired. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. + If you are using queue journaling, removing the message causes a copy to be kept in the journal queue, just as the class's method does. - When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. + When working with transactional queues, a rollback of a transaction causes any messages removed by a call to to be returned to the queue. The removal is not irreversible until the transaction is committed. - When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . + When you remove the current message, the cursor is moved to the next message. You do not have to call after calling . ]]> @@ -696,7 +696,7 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro ## Remarks An enumerator can only move in a forward direction. Use this method to start over at the beginning of the queue. - After calling , the cursor points to the first message. You do not need to call after calling to move the cursor forward to the first message in the queue. + After calling , the cursor points to the first message. You do not need to call after calling to move the cursor forward to the first message in the queue. ]]> diff --git a/xml/System.Messaging/MessagePropertyFilter.xml b/xml/System.Messaging/MessagePropertyFilter.xml index b60a9d9dab8..fb6e533ec67 100644 --- a/xml/System.Messaging/MessagePropertyFilter.xml +++ b/xml/System.Messaging/MessagePropertyFilter.xml @@ -38,13 +38,13 @@ ## Remarks Setting the on a instance controls the set of properties that are retrieved when peeking or receiving a message. The filter is set on the instance of that retrieves the message information. When you set a Boolean-valued member to `false`, you prevent the information of the associated property from being retrieved by the . - There are several filter properties that are not Boolean values. They are integer values that get or set the default sizes of the , , or . + There are several filter properties that are not Boolean values. They are integer values that get or set the default sizes of the , , or . Retrieving a limited set of properties helps improve performance because smaller amounts of data are transferred from the queue. When setting a property on , you are only indicating whether that property is retrieved when a message is received or peeked. You are not changing the associated property value for the . - The constructor sets all filter properties to their default values, which for the Boolean values is `false`. See the constructor topic for the defaults assigned to the integer-valued properties. + The constructor sets all filter properties to their default values, which for the Boolean values is `false`. See the constructor topic for the defaults assigned to the integer-valued properties. @@ -82,13 +82,13 @@ constructor sets all Boolean values to `false` and sets the integer-valued properties to the default values shown in the following table. + The constructor sets all Boolean values to `false` and sets the integer-valued properties to the default values shown in the following table. |Property|Default value| |--------------|-------------------| -||1024| -||255| -||255| +||1024| +||255| +||255| @@ -193,7 +193,7 @@ ## Remarks The property of the class specifies the type of acknowledgment messages the system posts in the administration queue, which determines when acknowledgments are generated. - Acknowledgments are returned from the destination queue and posted as messages to the specified by the original message. The type of acknowledgment generated depends on what was requested. + Acknowledgments are returned from the destination queue and posted as messages to the specified by the original message. The type of acknowledgment generated depends on what was requested. Read the property when receiving a message from an administration queue to verify the status of the message originally sent to the message queue. @@ -402,7 +402,7 @@ property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. + The property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. @@ -506,7 +506,7 @@ property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. + The property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. @@ -561,7 +561,7 @@ property of the class specifies the type of cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. + The property of the class specifies the type of cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. @@ -655,14 +655,14 @@ to set all Boolean properties to `false`. This causes no message properties to be retrieved when receiving messages. does not affect the values for , , or . + Use to set all Boolean properties to `false`. This causes no message properties to be retrieved when receiving messages. does not affect the values for , , or . - After calling , it is necessary to set at least one filter property to `true` in order to receive data related to a message. You can either set individual properties to `true`, or you can call or . + After calling , it is necessary to set at least one filter property to `true` in order to receive data related to a message. You can either set individual properties to `true`, or you can call or . ## Examples - The following code example calls the method. + The following code example calls the method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet37"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet37"::: @@ -737,7 +737,7 @@ ## Remarks The property of the class is required when an application sets a message property that is typically set by Message Queuing. It is used in the following two instances: -- When a message is passed by a connector application, the is required for the sending and receiving applications to interpret the security and acknowledgment properties of the message. +- When a message is passed by a connector application, the is required for the sending and receiving applications to interpret the security and acknowledgment properties of the message. - When sending application-encrypted messages, the property informs Message Queuing to use the symmetric key. @@ -893,7 +893,7 @@ property of the class represents the additional, application-defined information associated with the message, such as a binary large object. It is the responsibility of the application to interpret the contents of the . + The default extension size specifies the number of bytes to allocate for the message's extension. The property of the class represents the additional, application-defined information associated with the message, such as a binary large object. It is the responsibility of the application to interpret the contents of the . @@ -1205,7 +1205,7 @@ property of the class provides for additional application-defined information that is associated with the message, like a large binary object. It is the responsibility of the receiving application to interpret the contents of the . + The property of the class provides for additional application-defined information that is associated with the message, like a large binary object. It is the responsibility of the receiving application to interpret the contents of the . @@ -1667,7 +1667,7 @@ ## Remarks The property of the class indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. - If delivery of a message is guaranteed, the message is stored locally at every step until the message is successfully forwarded to the next computer. Setting to `true` on the message could affect the throughput. + If delivery of a message is guaranteed, the message is stored locally at every step until the message is successfully forwarded to the next computer. Setting to `true` on the message could affect the throughput. @@ -1876,7 +1876,7 @@ ## Remarks The property of the class specifies the version of Message Queuing used to send the message. The property is important to be aware of when using features like transaction processing, which is only supported by Message Queuing version 2.0 and later, or digital signatures, which are used to authenticate messages sent by version 1.0. - is set by the sending queue manager when the message is sent. + is set by the sending queue manager when the message is sent. @@ -1970,14 +1970,14 @@ to set all Boolean properties to `true`. This causes all message properties to be retrieved when receiving messages. does not affect the values for , , or . + Use to set all Boolean properties to `true`. This causes all message properties to be retrieved when receiving messages. does not affect the values for , , or . - After calling , you can set individual filter values to `false` in order to restrict the properties retrieved when the message is received. + After calling , you can set individual filter values to `false` in order to restrict the properties retrieved when the message is received. ## Examples - The following code example calls the method. + The following code example calls the method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet39"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet39"::: @@ -2013,44 +2013,44 @@ to set the following Boolean-valued properties to `true`. These are the most common properties a will typically interact with the following: + Use to set the following Boolean-valued properties to `true`. These are the most common properties a will typically interact with the following: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- - sets the properties in the following table to their default values. + sets the properties in the following table to their default values. |Property|Default value| |--------------|-------------------| -||1024| -||255| -||255| +||1024| +||255| +||255| - The property represents a on which has been called. + The property represents a on which has been called. ## Examples - The following code example calls the method. + The following code example calls the method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet38"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet38"::: diff --git a/xml/System.Messaging/MessageQueue.xml b/xml/System.Messaging/MessageQueue.xml index 5877ca3f43e..8a956b89eb0 100644 --- a/xml/System.Messaging/MessageQueue.xml +++ b/xml/System.Messaging/MessageQueue.xml @@ -64,17 +64,17 @@ The class is a wrapper around Message Queuing. There are multiple versions of Message Queuing, and using the class can result in slightly different behavior, depending on the operating system you are using. - The class provides a reference to a Message Queuing queue. You can specify a path in the constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call , , or , you must associate the new instance of the class with an existing queue. At that point, you can manipulate the queue properties such as and . + The class provides a reference to a Message Queuing queue. You can specify a path in the constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call , , or , you must associate the new instance of the class with an existing queue. At that point, you can manipulate the queue properties such as and . - supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, and , allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads. + supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, and , allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads. - When you create a new instance of the class, you are not creating a new Message Queuing queue. Instead, you can use the , , and methods to manage queues on the server. + When you create a new instance of the class, you are not creating a new Message Queuing queue. Instead, you can use the , , and methods to manage queues on the server. - Unlike , and are `static` members, so you can call them without creating a new instance of the class. + Unlike , and are `static` members, so you can call them without creating a new instance of the class. - You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . + You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . - For a list of initial property values for an instance of , see the constructor. + For a list of initial property values for an instance of , see the constructor. ## Examples The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. @@ -136,18 +136,18 @@ class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. + Use this overload to create a new instance of the class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. - The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. + The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. The following table shows initial property values for an instance of . |Property|Initial value| |--------------|-------------------| -||The values set by the parameterless constructor of the class.| -||| -||The values set by the parameterless constructor of the class. All the filter values are set to `true`.| -||`false`| +||The values set by the parameterless constructor of the class.| +||| +||The values set by the parameterless constructor of the class. All the filter values are set to `true`.| +||`false`| @@ -190,7 +190,7 @@ ## Remarks Use this overload when you want to tie the new instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the property to `true` or use the constructor that passes a read-access restriction parameter. - The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . + The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . The syntax of the `path` parameter depends on the type of queue it references, as shown in the following table. @@ -203,7 +203,7 @@ |Machine dead-letter queue|`MachineName`\\`Deadletter$`| |Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - Alternatively, you can use the or to describe the queue path, as shown in the following table. + Alternatively, you can use the or to describe the queue path, as shown in the following table. |Reference|Syntax|Example| |---------------|------------|-------------| @@ -216,21 +216,21 @@ |Property|Initial value| |--------------|-------------------| -||`false`| -||0| -||| -||The values set by the parameterless constructor of the class.| -||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| -||| -||| -||The value of the Message Queuing queue's computer name property.| -||| -||| -||The values set by the parameterless constructor of the class.| -||, if not set by the constructor.| -||, if not set by the constructor.| -||`false`| -||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| +||`false`| +||0| +||| +||The values set by the parameterless constructor of the class.| +||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| +||| +||| +||The value of the Message Queuing queue's computer name property.| +||| +||| +||The values set by the parameterless constructor of the class.| +||, if not set by the constructor.| +||, if not set by the constructor.| +||`false`| +||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| @@ -281,7 +281,7 @@ Setting `sharedModeDenyReceive` to `true` affects all objects that access the Message Queuing queue, including other applications. The effects of the parameter are not restricted to this application. - The constructor creates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . + The constructor creates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . The syntax of the `path` parameter depends on the type of queue. @@ -309,21 +309,21 @@ |Property|Initial value| |--------------|-------------------| -||`false`.| -||0.| -||.| -||The values set by the parameterless constructor of the class.| -||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| -||.| -||.| -||The value of the Message Queuing queue's computer name property.| -||.| -||.| -||The values set by the parameterless constructor of the class.| -||, if not set by the constructor.| -||, if not set by the constructor.| -||The value of the `sharedModeDenyReceive` parameter.| -||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| +||`false`.| +||0.| +||.| +||The values set by the parameterless constructor of the class.| +||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| +||.| +||.| +||The value of the Message Queuing queue's computer name property.| +||.| +||.| +||The values set by the parameterless constructor of the class.| +||, if not set by the constructor.| +||, if not set by the constructor.| +||The value of the `sharedModeDenyReceive` parameter.| +||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| @@ -502,7 +502,7 @@ ## Remarks Message authentication provides a way to ensure message integrity and to verify who sent the message. To request authentication, the sending application sets the message's authentication level. - When you set to `true`, you are restricting access to the queue on the server, not only to this instance. All clients working against the same Message Queuing queue will be affected. + When you set to `true`, you are restricting access to the queue on the server, not only to this instance. All clients working against the same Message Queuing queue will be affected. A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue. @@ -565,9 +565,9 @@ ## Remarks A message queue's base priority specifies how a message en route to that queue is treated as it travels through the network. You can set the property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. + A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. - applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0). + applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0). The following table shows whether this property is available in various Workgroup modes. @@ -627,21 +627,21 @@ to raise the event when a message becomes available in the queue. + In asynchronous processing, you use to raise the event when a message becomes available in the queue. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - If is `false`, the completion event is raised, but an exception will be thrown when calling . + If is `false`, the completion event is raised, but an exception will be thrown when calling . The following table shows whether this method is available in various Workgroup modes. @@ -655,7 +655,7 @@ ## Examples - The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. + The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: @@ -699,23 +699,23 @@ to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + In asynchronous processing, you use to raise the event when a message becomes available in the queue or when the specified interval of time has expired. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - If is `false`, the completion event is raised, but an exception will be thrown when calling . + If is `false`, the completion event is raised, but an exception will be thrown when calling . The following table shows whether this method is available in various Workgroup modes. @@ -729,7 +729,7 @@ ## Examples - The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called with a time-out of one minute, to initiate the asynchronous peek operation. When a event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out. + The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called with a time-out of one minute, to initiate the asynchronous peek operation. When a event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/CPP/mqbeginpeek_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_timeout.cs" id="Snippet1"::: @@ -777,29 +777,29 @@ to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + In asynchronous processing, you use to raise the event when a message becomes available in the queue or when the specified interval of time has expired. is also raised if a message already exists in the queue. Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the property of the that is associated with the operation. - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. For an illustration of this scenario, see the Example section. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. For an illustration of this scenario, see the Example section. You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - If is `false`, the completion event is raised, but an exception will be thrown when calling . + If is `false`, the completion event is raised, but an exception will be thrown when calling . The following table shows whether this method is available in various Workgroup modes. @@ -813,7 +813,7 @@ ## Examples - The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called, with a time-out of one minute. Each call to has a unique associated integer that identifies that particular operation. When a event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation. + The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called, with a time-out of one minute. Each call to has a unique associated integer that identifies that particular operation. When a event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/CPP/mqbeginpeek_timeoutstateobject.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_timeoutstateobject.cs" id="Snippet1"::: @@ -863,19 +863,19 @@ event is not raised. The other overloads of rely on this component to raise the event. + When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the event is not raised. The other overloads of rely on this component to raise the event. is also raised if a message already exists in the queue. - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. The following table shows whether this method is available in various Workgroup modes. @@ -889,7 +889,7 @@ ## Examples - The following code example creates an asynchronous peek operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyPeekCompleted`. When a event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen. + The following code example creates an asynchronous peek operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyPeekCompleted`. When a event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginPeek/cpp/class1.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/class1.cs" id="Snippet0"::: @@ -942,19 +942,19 @@ event is not raised. The other overloads of rely on this component to raise the event. + When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired. The event is not raised. The other overloads of rely on this component to raise the event. is also raised if a message already exists in the queue. - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. The following table shows whether this method is available in various Workgroup modes. @@ -1015,23 +1015,23 @@ to raise the event when a message has been removed from the queue. + In asynchronous processing, you use to raise the event when a message has been removed from the queue. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling . + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - If is `false`, the completion event is raised, but an exception will be thrown when calling . + If is `false`, the completion event is raised, but an exception will be thrown when calling . - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. ```csharp myMessageQueue.BeginTransaction(); @@ -1057,7 +1057,7 @@ myMessageQueue.BeginTransaction(); :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_mre.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_mre.vb" id="Snippet1"::: - The following code example queues asynchronous requests. The call to uses the in its return value. The `Main` routine waits for all asynchronous operations to be completed before exiting. + The following code example queues asynchronous requests. The call to uses the in its return value. The `Main` routine waits for all asynchronous operations to be completed before exiting. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_wh.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_wh.cs" id="Snippet2"::: @@ -1101,25 +1101,25 @@ myMessageQueue.BeginTransaction(); to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + In asynchronous processing, you use to raise the event when a message becomes available in the queue or when the specified interval of time has expired. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - If is `false`, the completion event is raised, but an exception will be thrown when calling . + If is `false`, the completion event is raised, but an exception will be thrown when calling . - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. ```csharp myMessageQueue.BeginTransaction(); @@ -1139,7 +1139,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds. When a event is raised, the event handler receives the message and writes the message body to the screen. + The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds. When a event is raised, the event handler receives the message and writes the message body to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive1/cpp/class1.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class1.cs" id="Snippet0"::: @@ -1186,29 +1186,29 @@ myMessageQueue.BeginTransaction(); to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + In asynchronous processing, you use to raise the event when a message becomes available in the queue or when the specified interval of time has expired. is also raised if a message already exists in the queue. Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the property of the that is associated with the operation. - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. ```csharp myMessageQueue.BeginTransaction(); @@ -1228,7 +1228,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds and a unique integer that identifies that particular message. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. + The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds and a unique integer that identifies that particular message. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive2/cpp/class1.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class11.cs" id="Snippet0"::: @@ -1277,25 +1277,25 @@ myMessageQueue.BeginTransaction(); event is not raised. The other overloads of rely on this component to raise the event. + When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the event is not raised. The other overloads of rely on this component to raise the event. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. ```csharp myMessageQueue.BeginTransaction(); @@ -1315,7 +1315,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example creates an asynchronous receive operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyReceiveCompleted`. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. + The following code example creates an asynchronous receive operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyReceiveCompleted`. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive3/cpp/class1.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class12.cs" id="Snippet0"::: @@ -1366,25 +1366,25 @@ myMessageQueue.BeginTransaction(); event is not raised. The other overloads of rely on this component to raise the event. + When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the event is not raised. The other overloads of rely on this component to raise the event. is also raised if a message already exists in the queue. - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. ```csharp myMessageQueue.BeginTransaction(); @@ -1455,9 +1455,9 @@ myMessageQueue.BeginTransaction(); indicates whether the application is able to peek or receive messages from the queue. If is `true`, the can receive or peek messages from the queue. Otherwise, it cannot. + indicates whether the application is able to peek or receive messages from the queue. If is `true`, the can receive or peek messages from the queue. Otherwise, it cannot. - is `false` if a queue is already open with exclusive read access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to read from a queue when is `false`, access is denied. + is `false` if a queue is already open with exclusive read access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to read from a queue when is `false`, access is denied. The following table shows whether this property is available in various Workgroup modes. @@ -1520,9 +1520,9 @@ myMessageQueue.BeginTransaction(); indicates whether the application is able to send messages to the queue. If is `true`, the can send messages to the queue. Otherwise, it cannot. + indicates whether the application is able to send messages to the queue. If is `true`, the can send messages to the queue. Otherwise, it cannot. - is `false` if a queue is already open with exclusive write access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to write to a queue when is `false`, access is denied. + is `false` if a queue is already open with exclusive write access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to write to a queue when is `false`, access is denied. The following table shows whether this property is available in various Workgroup modes. @@ -1582,9 +1582,9 @@ myMessageQueue.BeginTransaction(); ## Remarks The queue category allows an application to categorize its queues. For example, you can place all Billing queues in one category and all Order queues in another. - The property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + The property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. - It is not necessary to set the . The value can be `null`. + It is not necessary to set the . The value can be `null`. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. @@ -1637,7 +1637,7 @@ myMessageQueue.BeginTransaction(); , the format names stored in the cache are removed and handles opened and stored in the cache are closed. + When you call , the format names stored in the cache are removed and handles opened and stored in the cache are closed. The following table shows whether this method is available in various Workgroup modes. @@ -1651,7 +1651,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example calls . + The following code example calls . :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet8"::: @@ -1683,7 +1683,7 @@ myMessageQueue.BeginTransaction(); frees all resources associated with a , including shared resources if appropriate. The system re-acquires these resources automatically if they are still available, for example when you call the method, as in the following C# code. + frees all resources associated with a , including shared resources if appropriate. The system re-acquires these resources automatically if they are still available, for example when you call the method, as in the following C# code. ```csharp myMessageQueue.Send("Text 1."); @@ -1691,17 +1691,17 @@ myMessageQueue.Close(); myMessageQueue.Send("Text 2."); //Resources are re-acquired. ``` - When you call , all properties that directly access the Message Queuing queue are cleared out. The , , , and all remain as they were. + When you call , all properties that directly access the Message Queuing queue are cleared out. The , , , and all remain as they were. - does not always free the read and write handles to a queue, because they might be shared. You can take any of the following steps to ensure that frees the read and write handles to a queue: + does not always free the read and write handles to a queue, because they might be shared. You can take any of the following steps to ensure that frees the read and write handles to a queue: -- Create the with exclusive access. To do so, call the or constructor, and set the `sharedModeDenyReceive` parameter to `true`. +- Create the with exclusive access. To do so, call the or constructor, and set the `sharedModeDenyReceive` parameter to `true`. -- Create the with connection caching disabled. To do so, call the constructor and set the `enableConnectionCache` parameter to `false`. +- Create the with connection caching disabled. To do so, call the constructor and set the `enableConnectionCache` parameter to `false`. - Disable connection caching. To do so, set the property to `false`. - You should call for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue. + You should call for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue. The following table shows whether this method is available in various Workgroup modes. @@ -1764,7 +1764,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks Use this overload to create a non-transactional Message Queuing queue. - To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . + To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. @@ -1834,9 +1834,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. . + You can use this overload to create a transactional queue in Message Queuing. You can create a non-transactional queue, by setting the `transactional` parameter to `false` or by calling the other overload of . - To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . + To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. @@ -1934,7 +1934,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. refers to the queue on the Message Queuing server, not the instance. + refers to the queue on the Message Queuing server, not the instance. If the queue exists, this property represents the time the queue was created, adjusted to the local time of the server on which the queue exists. @@ -1998,33 +1998,33 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . + When you send any object that is not of type to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . - Although you set the properties through the object, the refers to the properties of the messages that are sent to the queue, not the queue itself. + Although you set the properties through the object, the refers to the properties of the messages that are sent to the queue, not the queue itself. The default values for the properties are shown in the following table. |Property|Default value| |--------------|-------------------| -||`AcknowledgeType.None`| -||`null`| -||Zero (0)| -||`true`| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||`HashAlgorithm.MD5`| -||Empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`AcknowledgeType.None`| +||`null`| +||Zero (0)| +||`true`| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||`HashAlgorithm.MD5`| +||Empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| The following table shows whether this property is available in various Workgroup modes. @@ -2090,7 +2090,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. For more syntax, see the property. - Alternatively, you can use the or to describe the queue path. + Alternatively, you can use the or to describe the queue path. |Reference|Syntax| |---------------|------------| @@ -2166,9 +2166,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. specifies the shared mode of the queue referenced by this . Set to `true` to indicate that only this should have access to peek or receive messages from the queue with the specified . If another or another application is associated with the same queue resource, that instance or application will not be able to peek or receive messages, but it can still send them. + specifies the shared mode of the queue referenced by this . Set to `true` to indicate that only this should have access to peek or receive messages from the queue with the specified . If another or another application is associated with the same queue resource, that instance or application will not be able to peek or receive messages, but it can still send them. - If is `false`, the queue is available to multiple applications for sending, peeking, or receiving messages. + If is `false`, the queue is available to multiple applications for sending, peeking, or receiving messages. The following table shows whether this property is available in various Workgroup modes. @@ -2220,9 +2220,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the memory it was occupying can be reclaimed by garbage collection. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the memory it was occupying can be reclaimed by garbage collection. - You should call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. + You should call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. ]]> @@ -2260,9 +2260,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. is `true`, the borrows handles from the cache each time you call , , or , rather than open new handles. This can improve performance. Using a connection cache also insulates the from changes in the network topology. + A connection cache is a list of references to structures that contain read or write handles to queues. When is `true`, the borrows handles from the cache each time you call , , or , rather than open new handles. This can improve performance. Using a connection cache also insulates the from changes in the network topology. - If you create a new connection to a queue when the connection cache is full, the overwrites the least recently accessed structure with the new connection. You can clear the cache entirely by calling , for example, if the format names of the queues you are working with have changed so that the previous read and write handles are no longer valid. + If you create a new connection to a queue when the connection cache is full, the overwrites the least recently accessed structure with the new connection. You can clear the cache entirely by calling , for example, if the format names of the queues you are working with have changed so that the previous read and write handles are no longer valid. The following table shows whether this property is available in various Workgroup modes. @@ -2317,11 +2317,11 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. and properties) cannot be encrypted. + When you specify that encryption is required for the messages sent to a queue, only the message bodies are encrypted. The other members (for example, the and properties) cannot be encrypted. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. + Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. The following table shows whether this property is available in various Workgroup modes. @@ -2372,13 +2372,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. event is raised, completes the operation that was initiated by the call. To do so, peeks the message. + When the event is raised, completes the operation that was initiated by the call. To do so, peeks the message. - can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. + can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. - is used to read the message that caused the event to be raised. + is used to read the message that caused the event to be raised. - If you want to continue to asynchronously peek messages, you can again call after calling . + If you want to continue to asynchronously peek messages, you can again call after calling . The following table shows whether this method is available in various Workgroup modes. @@ -2390,7 +2390,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Remote computer and direct format name|Yes| ## Examples - The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. + The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: @@ -2433,13 +2433,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. event is raised, completes the operation that was initiated by the call. To do so, receives the message. + When the event is raised, completes the operation that was initiated by the call. To do so, receives the message. - can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. + can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. - is used to read (removing from the queue) the message that caused the event to be raised. + is used to read (removing from the queue) the message that caused the event to be raised. - If you want to continue to asynchronously receive messages, you can again call after calling . + If you want to continue to asynchronously receive messages, you can again call after calling . The following table shows whether this method is available in various Workgroup modes. @@ -2495,12 +2495,12 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) + The method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) - is an expensive operation. Use it only when it is necessary within the application. + is an expensive operation. Use it only when it is necessary within the application. > [!NOTE] -> The method does not support the prefix. +> The method does not support the prefix. The syntax for the `path` parameter depends on the type of queue, as shown in the following table. @@ -2508,11 +2508,11 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |--------------|----------------------------| | Public queue | `MachineName`\\`QueueName` | - cannot be called to verify the existence of a remote private queue. + cannot be called to verify the existence of a remote private queue. For more syntax, see the property. - Alternatively, you can use the to describe the queue path. + Alternatively, you can use the to describe the queue path. | Reference | Syntax | |-----------|-------------------| @@ -2582,7 +2582,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks The property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later. - If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the into the associated before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation. + If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the into the associated before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation. The following table shows whether this property is available in various Workgroup modes. @@ -2660,7 +2660,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. - When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. + When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. @@ -2718,11 +2718,11 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. returns a static snapshot of the messages in the queue, not dynamic links to those messages. Therefore, you cannot use the array to modify the messages in the queue. If you want real-time, dynamic interaction with the queue (such as the ability to delete messages), call the method, which returns a dynamic list of the messages in the queue. + returns a static snapshot of the messages in the queue, not dynamic links to those messages. Therefore, you cannot use the array to modify the messages in the queue. If you want real-time, dynamic interaction with the queue (such as the ability to delete messages), call the method, which returns a dynamic list of the messages in the queue. - Because returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue. + Because returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue. - retrieves only those properties not filtered out by the property. + retrieves only those properties not filtered out by the property. The following table shows whether this method is available in various Workgroup modes. @@ -2734,7 +2734,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. | Remote computer and direct format name | Yes | ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet21"::: @@ -2822,7 +2822,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. for a remote computer when you are working offline because the application must have access to the directory service on the domain controller. + You can use a computer's identifier for two purposes, among others: to read the computer journal and to set security certificates. However, you cannot call for a remote computer when you are working offline because the application must have access to the directory service on the domain controller. The computer identifier (or machine identifier) is a that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the property is `true`. @@ -2838,7 +2838,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. | Remote computer and direct format name | No | ## Examples - The following code example calls . + The following code example calls . :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet14"::: @@ -2884,13 +2884,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. + creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. - Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. - If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. + If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. The following table shows whether this method is available in various Workgroup modes. @@ -2932,13 +2932,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. + creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. - Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. - If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. + If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. The following table shows whether this method is available in various Workgroup modes. @@ -2989,13 +2989,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. returns an enumeration of all the public queues that are on the network. + This overload of returns an enumeration of all the public queues that are on the network. - Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue list for queues deleted or added beyond the cursor's current position. Additions or deletion of queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue list for queues deleted or added beyond the cursor's current position. Additions or deletion of queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. - If you want a static snapshot of the queues on the network rather than a dynamic connection to them, call or . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. + If you want a static snapshot of the queues on the network rather than a dynamic connection to them, call or . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. The following table shows whether this method is available in various Workgroup modes. @@ -3049,13 +3049,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. returns a listing of all the public queues on the network that satisfy criteria defined in the application criteria. You can specify the criteria to include, for example, queue creation or modification time, computer name, label, category, or any combination of these. + This overload of returns a listing of all the public queues on the network that satisfy criteria defined in the application criteria. You can specify the criteria to include, for example, queue creation or modification time, computer name, label, category, or any combination of these. - Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue that occurs beyond the cursor's current position. Changes to queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue that occurs beyond the cursor's current position. Changes to queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. - If you want a static snapshot of the queues on the network rather than a dynamic connection to them, specify criteria for or call . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. Calling , , or provides the same results as calling with the filtering criteria of , , and , respectively. + If you want a static snapshot of the queues on the network rather than a dynamic connection to them, specify criteria for or call . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. Calling , , or provides the same results as calling with the filtering criteria of , , and , respectively. The following table shows whether this method is available in various Workgroup modes. @@ -3109,7 +3109,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. retrieves a static snapshot of the queues on a specified computer. + retrieves a static snapshot of the queues on a specified computer. The following table shows whether this method is available in various Workgroup modes. @@ -3172,9 +3172,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. , , or last modified time use another overload of this method. (Alternatively, you can use , , or .) + Use this overload if you want a complete list of all the public queues on the network. If you want to restrict the list by certain criteria, such as , , or last modified time use another overload of this method. (Alternatively, you can use , , or .) - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . The following table shows whether this method is available in various Workgroup modes. @@ -3228,9 +3228,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. class contains specific methods that provide that functionality (, , and , respectively). Use this overload to get a list of all the public queues on the network that meet more than one of these criteria (for example, if you want to specify both a label and a category). You can also filter by message criteria other than , , and . For example, you use this overload to filter by a queue's last-modified time. Simply create a new instance of the class, set the appropriate properties in the instance, and pass the instance as the `criteria` parameter. + If you want to filter all the public queues on the network by label, category, or computer name, the class contains specific methods that provide that functionality (, , and , respectively). Use this overload to get a list of all the public queues on the network that meet more than one of these criteria (for example, if you want to specify both a label and a category). You can also filter by message criteria other than , , and . For example, you use this overload to filter by a queue's last-modified time. Simply create a new instance of the class, set the appropriate properties in the instance, and pass the instance as the `criteria` parameter. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . The following table shows whether this method is available in various Workgroup modes. @@ -3285,9 +3285,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + Use this method to filter the public queues by category. The property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the category as part of the you pass into the method. + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the category as part of the you pass into the method. The following table shows whether this method is available in various Workgroup modes. @@ -3345,7 +3345,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks Use this method to filter the public queues by label. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the label as part of the you pass into the method. + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the label as part of the you pass into the method. The following table shows whether this method is available in various Workgroup modes. @@ -3404,7 +3404,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks Use this method to filter the public queues by computer. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the computer name as part of the you pass into the method. + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the computer name as part of the you pass into the method. The following table shows whether this method is available in various Workgroup modes. @@ -3538,7 +3538,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. or . + This member is frequently used when setting or . @@ -3576,7 +3576,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. If the specified time interval is , the process thread remains blocked until a new message is available. On the other hand, and (the asynchronous methods), allow the main application tasks to continue in a separate thread until a message arrives in the queue. + supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. If the specified time interval is , the process thread remains blocked until a new message is available. On the other hand, and (the asynchronous methods), allow the main application tasks to continue in a separate thread until a message arrives in the queue. @@ -3629,7 +3629,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks The maximum length of a message queue label is 124 characters. - The property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + The property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. The following table shows whether this property is available in various Workgroup modes. @@ -3691,9 +3691,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. + The last modification time includes when the queue was created and any property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. - You must call before getting the property; otherwise, the modification time associated with this might not be current. + You must call before getting the property; otherwise, the modification time associated with this might not be current. The following table shows whether this property is available in various Workgroup modes. @@ -3756,7 +3756,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. is an integral component of the friendly name syntax of the queue . The following table shows the syntax you should use for a queue of a specified type when you want to identify the queue path using its friendly name. + The is an integral component of the friendly name syntax of the queue . The following table shows the syntax you should use for a queue of a specified type when you want to identify the queue path using its friendly name. |Queue type|Syntax| |----------------|------------| @@ -3767,11 +3767,11 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Machine dead-letter queue|`MachineName`\\`Deadletter$`| |Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. + Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. - If you define the in terms of the , the application throws an exception when working offline because the domain controller is required for path translation. Therefore, you must use the for the syntax when working offline. + If you define the in terms of the , the application throws an exception when working offline because the domain controller is required for path translation. Therefore, you must use the for the syntax when working offline. - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. The following table shows whether this property is available in various Workgroup modes. @@ -3841,7 +3841,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. provides access to the Message Queuing journal storage limit. It is relevant only when is `true`. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change + provides access to the Message Queuing journal storage limit. It is relevant only when is `true`. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change If you store messages in a journal or dead-letter queue, you should periodically clear the queue to remove messages that are no longer needed. Messages in such a queue count toward the message quota for the computer where the queue resides. (The administrator sets the computer quota.) @@ -3908,7 +3908,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. provides access to the Message Queuing message storage limit, which is separate from the computer's message quota that the administrator defines. For more information about the message quota, see . + The provides access to the Message Queuing message storage limit, which is separate from the computer's message quota that the administrator defines. For more information about the message quota, see . Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change @@ -3976,55 +3976,55 @@ The name of the computer is not valid, possibly because the syntax is incorrect. receives or peeks. When the receives or peeks a message from the server queue, it retrieves only those properties for which the value is `true`. + This filter is a set of Boolean values restricting the message properties that the receives or peeks. When the receives or peeks a message from the server queue, it retrieves only those properties for which the value is `true`. - The following shows initial property values for the property. These settings are identical to calling on a . + The following shows initial property values for the property. These settings are identical to calling on a . |Property|Default value| |--------------|-------------------| -||`false`| -||`false`| -||`true`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`true`| -||1024 bytes| -||255 bytes| -||255 bytes| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`true`| +||1024 bytes| +||255 bytes| +||255 bytes| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| The following table shows whether this property is available in various Workgroup modes. @@ -4038,7 +4038,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example uses the to restrict the message properties received. + The following code example uses the to restrict the message properties received. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.MessageReadPropertyFilter/CPP/mqmessagereadpropertyfilter.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/MessageReadPropertyFilter/mqmessagereadpropertyfilter.cs" id="Snippet1"::: @@ -4199,16 +4199,16 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Use "." to represent the local computer. - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. - Alternatively, you can use the or to describe the queue path, as shown in the following table. + Alternatively, you can use the or to describe the queue path, as shown in the following table. |Reference|Syntax|Example| |---------------|------------|-------------| |Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112| |Label|`Label:` [ *label* ]|`Label:` TheLabel| - If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. @@ -4283,11 +4283,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to peek a queue, or to wait until a message exists in the queue. - The method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. + The method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload does not specify a time-out, the application might wait indefinitely. If you need the application processing to continue without waiting, use the asynchronous method. Alternatively, you can specify a time-out for a message to arrive in the queue by using the overload of that specifies a time-out. + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload does not specify a time-out, the application might wait indefinitely. If you need the application processing to continue without waiting, use the asynchronous method. Alternatively, you can specify a time-out for a message to arrive in the queue by using the overload of that specifies a time-out. The following table shows whether this method is available in various Workgroup modes. @@ -4301,7 +4301,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following examples use the method on a queue. + The following examples use the method on a queue. In the first example, the application waits until a message becomes available in the queue. Note that the first example does not access the message that arrives; it merely pauses processing until a message arrives. If a message already exists in the queue, it will return immediately. @@ -4349,11 +4349,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to peek a queue, or to wait a specified period of time until a message exists in the queue. The method returns immediately if a message already exists in the queue. - The method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. + The method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. The following table shows whether this method is available in various Workgroup modes. @@ -4367,7 +4367,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example uses the method with a time-out of zero to check whether the queue is empty. + The following code example uses the method with a time-out of zero to check whether the queue is empty. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Peek_timeout/CPP/mqpeek_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Peek/mqpeek_timeout.cs" id="Snippet1"::: @@ -4416,9 +4416,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to peek a queue, or to wait a specified period of time until a message exists in the queue. The method returns immediately if a message already exists in the queue. - The method reads, but does not remove, a message from the queue. The method, on the other hand, both reads and removes a message from the queue. + The method reads, but does not remove, a message from the queue. The method, on the other hand, both reads and removes a message from the queue. - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. The following table shows whether this method is available in various Workgroup modes. @@ -4480,11 +4480,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. + This method looks in the queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. The following table shows whether this method is available in various Workgroup modes. @@ -4544,13 +4544,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, and no new message arrives in the queue within the period specified by the `timeout` parameter, an exception is thrown. + This method looks in the queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, and no new message arrives in the queue within the period specified by the `timeout` parameter, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. The following table shows whether this method is available in various Workgroup modes. @@ -4564,7 +4564,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet5"::: @@ -4622,9 +4622,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message. + Use to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message. - Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. The following table shows whether this method is available in various Workgroup modes. @@ -4638,7 +4638,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet6"::: @@ -4683,11 +4683,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message and a new message does not arrive before the time-out occurs. + Use to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message and a new message does not arrive before the time-out occurs. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. The following table shows whether this method is available in various Workgroup modes. @@ -4701,7 +4701,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet7"::: @@ -4758,7 +4758,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - To read a message with a specified lookup identifier and remove it from the queue, use the method. + To read a message with a specified lookup identifier and remove it from the queue, use the method. The following table shows whether this method is available in various Workgroup modes. @@ -4821,7 +4821,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - To read a message with a specified identifier and remove it from the queue, use the method. + To read a message with a specified identifier and remove it from the queue, use the method. The following table shows whether this method is available in various Workgroup modes. @@ -4871,16 +4871,16 @@ The name of the computer is not valid, possibly because the syntax is incorrect. is used in asynchronous processing to raise the event when a message is available in the queue. + is used in asynchronous processing to raise the event when a message is available in the queue. - is used to complete the operation initiated by a call to and peek the message when the event is raised. + is used to complete the operation initiated by a call to and peek the message when the event is raised. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). ## Examples - The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation + The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: @@ -4933,7 +4933,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet29"::: @@ -4983,7 +4983,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. + You can combine the with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. |Queue type|Syntax| |----------------|------------| @@ -4993,7 +4993,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Use "." to represent the local computer. - Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. + Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. The following table shows whether this property is available in various Workgroup modes. @@ -5056,7 +5056,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. provides a native Windows handle to the message queue object that is used for peeking and receiving messages from the queue. If you change the path of the queue, the handle is closed and reopened with a new value. + The provides a native Windows handle to the message queue object that is used for peeking and receiving messages from the queue. If you change the path of the queue, the handle is closed and reopened with a new value. The following table shows whether this property is available in various Workgroup modes. @@ -5111,11 +5111,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to receive a message from a queue, or wait until there are messages in the queue. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5172,13 +5172,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to receive a message from a transactional queue using the internal transaction context defined by the `transaction` parameter, or wait until there are messages in the queue. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5244,13 +5244,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5264,7 +5264,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet9"::: @@ -5310,11 +5310,11 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to receive a message and return in a specified period of time if there are no messages in the queue. - The method allows for the synchronous reading of a message, removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. + The method allows for the synchronous reading of a message, removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5417,13 +5417,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to receive a message from a transactional queue using the internal transaction context defined by the `transaction` parameter, and return within a specified period of time if there are no messages in the queue. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5497,13 +5497,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5571,13 +5571,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to receive a message from a transactional queue using the internal transaction context defined by the `transaction` parameter, and return within a specified period of time if there are no messages in the queue. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. Because this method is called on a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . + To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5649,13 +5649,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. + The method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. If this method is called to receive a message from a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . + To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . The following table shows whether this method is available in various Workgroup modes. @@ -5721,13 +5721,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application. + This method looks in the non-transactional queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method retrieves a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method retrieves a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. The following table shows whether this method is available in various Workgroup modes. @@ -5787,15 +5787,15 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using the internal transaction context defined by the `transaction` parameter. + This method looks in the transactional queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using the internal transaction context defined by the `transaction` parameter. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -5809,7 +5809,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet14"::: @@ -5864,7 +5864,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using a transaction context defined by the `transactionType` parameter. + This method looks in the queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. @@ -5872,9 +5872,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -5888,7 +5888,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet11"::: @@ -5936,15 +5936,15 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + This method looks in the non-transactional queue referenced by the for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. The following table shows whether this method is available in various Workgroup modes. @@ -5958,7 +5958,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet10"::: @@ -6010,17 +6010,17 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using the internal transaction context defined by the `transaction` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + This method looks in the transactional queue referenced by the for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using the internal transaction context defined by the `transaction` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6034,7 +6034,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet13"::: @@ -6096,17 +6096,17 @@ The name of the computer is not valid, possibly because the syntax is incorrect. for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using a transaction context defined by the `transactionType` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + This method looks in the queue referenced by the for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using a transaction context defined by the `transactionType` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6120,7 +6120,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet12"::: @@ -6184,9 +6184,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. The following table shows whether this method is available in various Workgroup modes. @@ -6200,7 +6200,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet16"::: @@ -6251,9 +6251,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6267,7 +6267,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet17"::: @@ -6330,9 +6330,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6346,7 +6346,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet15"::: @@ -6396,15 +6396,15 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known identifier and remove it from the queue. This method returns immediately if the message with the identifier specified by the `id` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. The following table shows whether this method is available in various Workgroup modes. @@ -6418,7 +6418,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet20"::: @@ -6472,17 +6472,17 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known identifier and remove it from the queue, using the internal transaction context defined by the `transaction` parameter. This method returns immediately if the message with the identifier specified by the `id` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the timeout period specified by the `timeout` parameter. + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the timeout period specified by the `timeout` parameter. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message, unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message, unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6496,7 +6496,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet18"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet18"::: @@ -6560,19 +6560,19 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known identifier and remove it from the queue. This method returns immediately if the message with the identifier specified by the `id` parameter is in the queue, using a transaction context defined by the `transactionType` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6586,7 +6586,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet19"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet19"::: @@ -6648,7 +6648,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - To read a message with a specified lookup identifier without removing it from the queue, use the method. + To read a message with a specified lookup identifier without removing it from the queue, use the method. The following table shows whether this method is available in various Workgroup modes. @@ -6715,7 +6715,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. The following table shows whether this method is available in various Workgroup modes. @@ -6785,7 +6785,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. + To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. @@ -6843,16 +6843,16 @@ The name of the computer is not valid, possibly because the syntax is incorrect. is used in asynchronous processing to raise the event when a message is available in the queue. + is used in asynchronous processing to raise the event when a message is available in the queue. - is used to complete the operation initiated by a call to and peek the message when the event is raised. + is used to complete the operation initiated by a call to and peek the message when the event is raised. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). ## Examples - The following code example creates an event handler named `MyReceiveCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous receive operation on the queue that is located at the path ".\myQueue". When a event is raised, the example receives the message and writes its body to the screen. The example then calls again to initiate a new asynchronous receive operation. + The following code example creates an event handler named `MyReceiveCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous receive operation on the queue that is located at the path ".\myQueue". When a event is raised, the example receives the message and writes its body to the screen. The example then calls again to initiate a new asynchronous receive operation. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/CPP/mqreceivecompletedeventhandler.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/ReceiveCompleted/mqreceivecompletedeventhandler.cs" id="Snippet1"::: @@ -6891,7 +6891,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. synchronizes the properties of a with its associated Message Queuing server resource. If any property, such as or , has changed on the server since the time the was created, updates the with the new information. + synchronizes the properties of a with its associated Message Queuing server resource. If any property, such as or , has changed on the server since the time the was created, updates the with the new information. The following table shows whether this method is available in various Workgroup modes. @@ -6905,7 +6905,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet28"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet28"::: @@ -6939,7 +6939,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. , you return the permission list to its default values. Generally, this grants the queue creator all permissions, and gives the group Everyone the following rights: + When you call , you return the permission list to its default values. Generally, this grants the queue creator all permissions, and gives the group Everyone the following rights: - Get the properties of the queue. @@ -6959,7 +6959,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet27"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet27"::: @@ -7010,9 +7010,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7083,9 +7083,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -7167,9 +7167,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7183,7 +7183,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet2"::: @@ -7241,9 +7241,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . + The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7257,7 +7257,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet1"::: @@ -7316,9 +7316,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -7339,7 +7339,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet4"::: @@ -7408,9 +7408,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7424,7 +7424,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet3"::: @@ -7490,7 +7490,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The trustee you specify when you construct the `ace` parameter can be an individual user, a group of users, or a computer. If the trustee is an individual, use the format `DOMAIN`\\`user`. You can specify "." for the trustee to indicate the local computer. - The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. The system examines each in sequence until one of the following events occurs: @@ -7560,7 +7560,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet26"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet26"::: @@ -7604,7 +7604,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The trustee you specify when you construct the `ace` parameter can be an individual user, a group of users, or a computer. If the trustee is an individual, use the format `DOMAIN`\\`user`. You can specify "." for the trustee to indicate the local computer. - The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. The system examines each in sequence until one of the following events occurs: @@ -7652,7 +7652,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet24"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet24"::: @@ -7697,7 +7697,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to grant specified rights to an individual user. The user can be any valid trustee, which includes individual users, groups of users, or a computer. If the user is an individual, use the format `DOMAIN`\\`user` for the `user` parameter. You can specify "." for the `user` parameter to indicate the local computer. - The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. The system examines each in sequence until one of the following events occurs: @@ -7747,7 +7747,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet23"::: @@ -7794,7 +7794,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this overload to grant, deny, or revoke specified rights for an individual user. The user can be any valid trustee, which includes individual users, groups of users, or a computer. If the user is an individual, use the format `DOMAIN`\\`user` for the `user` parameter. You can specify "." for the `user` parameter to indicate the local computer. - The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + The permissions you assign through add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. The system examines each in sequence until one of the following events occurs: @@ -7842,7 +7842,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example demonstrates the use of . + The following code example demonstrates the use of . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet25"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet25"::: @@ -7894,7 +7894,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. or event results from a or request, respectively, to a specific thread. Typically, the is set when its related component is placed inside a control or a form, because those components are bound to a specific thread. + A or event results from a or request, respectively, to a specific thread. Typically, the is set when its related component is placed inside a control or a form, because those components are bound to a specific thread. Typically, the synchronizing object marshals a method call into a single thread. @@ -7941,7 +7941,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Transactional messaging refers to the coupling of several related messages into a single transaction. Sending messages as part of a transaction ensures that the messages are delivered in order, delivered only once, and successfully retrieved from their destination queue. - If a queue is transactional, it accepts only messages that are sent as part of a transaction. However, a non-transactional message can be sent or received from a local transaction queue without explicitly using transactional , , and syntax. If a non-transactional message is sent to a transactional queue, this component creates a single-message transaction for it, except in the case of referencing a queue on a remote computer using a direct format name. In this situation, if you do not specify a transaction context when sending a message, one is not created for you and the message will be sent to the dead-letter queue. + If a queue is transactional, it accepts only messages that are sent as part of a transaction. However, a non-transactional message can be sent or received from a local transaction queue without explicitly using transactional , , and syntax. If a non-transactional message is sent to a transactional queue, this component creates a single-message transaction for it, except in the case of referencing a queue on a remote computer using a direct format name. In this situation, if you do not specify a transaction context when sending a message, one is not created for you and the message will be sent to the dead-letter queue. If you send a non-transactional message to a transactional queue, you will not be able to roll back the message in the event of an exception. @@ -8080,7 +8080,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. provides a native Windows handle to the message queue object that is used for sending messages to the queue. If you change the path of the queue, the handle is closed and reopened with a new value. + The provides a native Windows handle to the message queue object that is used for sending messages to the queue. If you change the path of the queue, the handle is closed and reopened with a new value. The following table shows whether this property is available in various Workgroup modes. diff --git a/xml/System.Messaging/MessageQueueAccessControlEntry.xml b/xml/System.Messaging/MessageQueueAccessControlEntry.xml index d5c43d15ba6..9c863ae8ca7 100644 --- a/xml/System.Messaging/MessageQueueAccessControlEntry.xml +++ b/xml/System.Messaging/MessageQueueAccessControlEntry.xml @@ -21,17 +21,17 @@ class to specify rights to apply to a trustee. These rights include peeking, receiving, or sending messages; viewing or modifying queue properties or permissions; and deleting queues. The class's method provides overloads for passing an instance of this class directly into the method, or adding it to an instance of so that you can add rights for more than one trustee at a time. The new access right is appended to the end of the queue's discretionary access control list (DACL), which identifies the users and groups that can access the queue. + Use the class to specify rights to apply to a trustee. These rights include peeking, receiving, or sending messages; viewing or modifying queue properties or permissions; and deleting queues. The class's method provides overloads for passing an instance of this class directly into the method, or adding it to an instance of so that you can add rights for more than one trustee at a time. The new access right is appended to the end of the queue's discretionary access control list (DACL), which identifies the users and groups that can access the queue. There are some exceptions to this generalization about where the new right is added and its effects. For more information, see . - An overload of the constructor allows you specify a member to indicate whether to allow or deny rights to the trustee. The order in which rights are allowed or denied in the resource's DACL affects whether the trustee has the specified rights. For example, if rights have already been granted to the trustee and you later add an entry that denies them, the system finds the granted rights first, so the user is granted rights you might have intended they be denied. You can use two entry types to override this behavior: `Set` and `Revoke`. For more information about controlling the way in which access rights are determined, see the enumeration topic. + An overload of the constructor allows you specify a member to indicate whether to allow or deny rights to the trustee. The order in which rights are allowed or denied in the resource's DACL affects whether the trustee has the specified rights. For example, if rights have already been granted to the trustee and you later add an entry that denies them, the system finds the granted rights first, so the user is granted rights you might have intended they be denied. You can use two entry types to override this behavior: `Set` and `Revoke`. For more information about controlling the way in which access rights are determined, see the enumeration topic. The class is associated with security based on access control lists (ACLs), which you can use to give users access to the Message Queuing system itself. This is different from code access security, which is implemented through the and related classes. Message Queuing code access security defines queue-specific operations or queue access that an application might require that is subject to security control; it does not represent a right for the application to perform these operations or receive access in and of itself. See the topic [Code Access Security](/dotnet/framework/misc/code-access-security) for more information about code access security. - To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. + To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. - You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . + You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . ]]> @@ -79,7 +79,7 @@ ## Remarks Use this overload of the constructor to grant rights to the specified trustee. The rights you specify in the `rights` parameter are a bitwise combination of members of the bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. - Pass this instance of directly into an overload of the method to grant rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. + Pass this instance of directly into an overload of the method to grant rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. ]]> @@ -121,7 +121,7 @@ For more information about granting or denying rights, see the topic. For two members, `Allow` and `Deny`, there may be preexisting and possibly contradictory access rights, so the order in which the rights appear in the queue's discretionary access control list (DACL) affects whether the right is ultimately granted. Two other members, `Set` and `Revoke`, overwrite any existing rights. Use the member whose behavior is applicable to your application. - Pass this instance of directly into an overload of the method to grant or deny rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. + Pass this instance of directly into an overload of the method to grant or deny rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. ]]> @@ -155,7 +155,7 @@ property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . + The property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . ]]> diff --git a/xml/System.Messaging/MessageQueueCriteria.xml b/xml/System.Messaging/MessageQueueCriteria.xml index c6947870b34..8b01bb18946 100644 --- a/xml/System.Messaging/MessageQueueCriteria.xml +++ b/xml/System.Messaging/MessageQueueCriteria.xml @@ -21,13 +21,13 @@ class provides a number of methods that enable you to filter your search for public queues on the network. Specific methods for filtering by queue label, category, or server location are the , , and . + The class provides a number of methods that enable you to filter your search for public queues on the network. Specific methods for filtering by queue label, category, or server location are the , , and . - The class, when used with the method, allows you to refine your filter. You can specify search criteria not specifically addressed through one of the `GetPublicQueuesBy`* methods, or by multiple criteria. You can pass a instance into the method in order to search, for example, by queue creation or modification times, the computer the queue resides on, the queue label or category, or any combination of these properties. + The class, when used with the method, allows you to refine your filter. You can specify search criteria not specifically addressed through one of the `GetPublicQueuesBy`* methods, or by multiple criteria. You can pass a instance into the method in order to search, for example, by queue creation or modification times, the computer the queue resides on, the queue label or category, or any combination of these properties. When filtering by multiple properties, the criteria are composed by applying the `AND` operator to the set of properties. Thus, when you specify a value for the property together with the property, you are asking for all queues that were created after a specified time and that reside on a specific computer. - When you set any property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. resets all properties into a "not set" default state. + When you set any property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. resets all properties into a "not set" default state. You must set a property before trying to read it; otherwise, an exception is thrown. @@ -93,7 +93,7 @@ ## Remarks The queue category allows an application to categorize its queues. For example, you can place all Billing queues in one category and all Order queues in another. The property is application-defined and has no intrinsic meaning to Message Queuing. - If you are filtering only by category when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the category, set this property and pass the parameter into . + If you are filtering only by category when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the category, set this property and pass the parameter into . ]]> @@ -127,9 +127,9 @@ , the method sets flags related to each of the properties, which indicate that no properties are to be included when the application creates the search filter. resets all properties that currently have values into a "not set" default state. Any properties that you subsequently change are combined using the logical `AND` operator to define a new filter for the method. When you change the property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. + When you call , the method sets flags related to each of the properties, which indicate that no properties are to be included when the application creates the search filter. resets all properties that currently have values into a "not set" default state. Any properties that you subsequently change are combined using the logical `AND` operator to define a new filter for the method. When you change the property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. - You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. + You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. ]]> @@ -159,9 +159,9 @@ properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no upper boundary on the date. + The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no upper boundary on the date. - If you try to set to a later value than , is reset to the same (new) value as . + If you try to set to a later value than , is reset to the same (new) value as . ]]> @@ -195,9 +195,9 @@ properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no lower boundary on the date. + The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no lower boundary on the date. - If you try to set to an earlier value than , is reset to the same (new) value as . + If you try to set to an earlier value than , is reset to the same (new) value as . ]]> @@ -233,7 +233,7 @@ ## Remarks A message queue's label is an application-defined description of the queue. It does not have any intrinsic meaning to Message Queuing. - If you are filtering only by label when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the label, set this property and pass the parameter into . + If you are filtering only by label when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the label, set this property and pass the parameter into . ]]> @@ -267,11 +267,11 @@ reflects the name of the server on which the queue resides, without preceding backslashes (\\\\). + A message queue's reflects the name of the server on which the queue resides, without preceding backslashes (\\\\). - If you are filtering only by computer name when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the computer name, set this property and pass the parameter into . + If you are filtering only by computer name when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the computer name, set this property and pass the parameter into . - You can also search for private queues on the network by specifying a computer name in the method. + You can also search for private queues on the network by specifying a computer name in the method. ]]> @@ -311,9 +311,9 @@ ## Remarks A queue's modification flag is set when you change the properties of a queue, but not when a message is read or written to the queue. - The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no upper boundary on the date. + The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no upper boundary on the date. - If you try to set to a later value than , is reset to the same (new) value as . + If you try to set to a later value than , is reset to the same (new) value as . ]]> @@ -349,9 +349,9 @@ ## Remarks A queue's modification flag is set when you change the properties of a queue, but not when a message is read or written to the queue. - The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no lower boundary on the date. + The properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no lower boundary on the date. - If you try to set to an earlier value than , is reset to the same (new) value as . + If you try to set to an earlier value than , is reset to the same (new) value as . ]]> diff --git a/xml/System.Messaging/MessageQueueEnumerator.xml b/xml/System.Messaging/MessageQueueEnumerator.xml index ea80bea867f..751fd05b1ea 100644 --- a/xml/System.Messaging/MessageQueueEnumerator.xml +++ b/xml/System.Messaging/MessageQueueEnumerator.xml @@ -30,9 +30,9 @@ ## Remarks Use for dynamic interaction with queues on the network. Methods available through the class can return either a containing a dynamic list of queues, or an array that contains a snapshot of the queue collection at the time the specified method was called. - There is no defined ordering of queues in a network. They are not ordered, for example, by computer, label, public or private status, or other user-accessible criteria. A is a cursor, initialized to the head of a dynamic list. You can move the cursor to the first queue of the enumeration by calling . After the enumerator has been initialized, you can use to step forward through the remaining queues. + There is no defined ordering of queues in a network. They are not ordered, for example, by computer, label, public or private status, or other user-accessible criteria. A is a cursor, initialized to the head of a dynamic list. You can move the cursor to the first queue of the enumeration by calling . After the enumerator has been initialized, you can use to step forward through the remaining queues. - It is not possible to step backward with a . A cursor only allows forward movement through the queue enumeration. However, you can call to reset the enumeration and put the cursor at the beginning of the list again. Because the enumerator is dynamic, a queue that is appended beyond the cursor's current position can be accessed by the enumerator. A queue that is inserted before the cursor's current position cannot be accessed without first calling Reset. + It is not possible to step backward with a . A cursor only allows forward movement through the queue enumeration. However, you can call to reset the enumeration and put the cursor at the beginning of the list again. Because the enumerator is dynamic, a queue that is appended beyond the cursor's current position can be accessed by the enumerator. A queue that is inserted before the cursor's current position cannot be accessed without first calling Reset. @@ -73,7 +73,7 @@ , to the queue enumerator during the lifetime of the cursor. When you finish working with the enumerator, call to release the resources associated with the handle. + The operating system retains an open handle, , to the queue enumerator during the lifetime of the cursor. When you finish working with the enumerator, call to release the resources associated with the handle. ]]> @@ -104,9 +104,9 @@ is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first queue in the enumeration. + When the enumerator is created, it does not point to anything, so is not valid and will throw an exception if it is accessed. You must call to position the cursor at the first queue in the enumeration. - Multiple calls to with no intervening calls to will return the same object. + Multiple calls to with no intervening calls to will return the same object. ]]> @@ -155,7 +155,7 @@ allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + Calling allows the resources used by the to be reallocated for other purposes. For more information about , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). ]]> @@ -190,7 +190,7 @@ method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -229,7 +229,7 @@ . Application code should not call this method; an object's Finalize method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. +This method overrides . Application code should not call this method; an object's Finalize method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v=vs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -261,7 +261,7 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro instance, call to free this handle to the resource. + When you no longer need this instance, call to free this handle to the resource. ]]> @@ -299,11 +299,11 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro returns `false` immediately if there are no queues associated with the enumeration. + returns `false` immediately if there are no queues associated with the enumeration. - will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. + will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. - Upon creation, an enumerator is conceptually positioned before the first of the enumeration, and the first call to brings the first queue of the enumeration into view. + Upon creation, an enumerator is conceptually positioned before the first of the enumeration, and the first call to brings the first queue of the enumeration into view. ]]> @@ -342,7 +342,7 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro ## Remarks An enumerator moves in a forward-only direction. Use this method to return to the beginning of the enumeration of queues. - positions the cursor at the first queue in the list. You do not need to call after calling to move the cursor forward to the first queue in the enumeration. + positions the cursor at the first queue in the list. You do not need to call after calling to move the cursor forward to the first queue in the enumeration. ]]> diff --git a/xml/System.Messaging/MessageQueueException.xml b/xml/System.Messaging/MessageQueueException.xml index 1d0556e0b36..5b95f169829 100644 --- a/xml/System.Messaging/MessageQueueException.xml +++ b/xml/System.Messaging/MessageQueueException.xml @@ -174,7 +174,7 @@ property contains a string associated with this that more fully describes the source of the error. + The property contains a string associated with this that more fully describes the source of the error. ]]> diff --git a/xml/System.Messaging/MessageQueueInstaller.xml b/xml/System.Messaging/MessageQueueInstaller.xml index e2e56c3188f..b361448a078 100644 --- a/xml/System.Messaging/MessageQueueInstaller.xml +++ b/xml/System.Messaging/MessageQueueInstaller.xml @@ -25,15 +25,15 @@ To install a queue, create a project installer class that inherits from the , and set the for the class to `true`. Within your project, create a instance for each queue in the installation and add the instance to your project installer class. - When creating a instance, you can optionally pass an existing (for example, from a test server) to the constructor. This approach automatically provides the configuration settings for the new queue by mirroring the settings of the queue passed in. Alternatively, you can manually set the properties in the instance to the states you want and call the parameterless constructor. + When creating a instance, you can optionally pass an existing (for example, from a test server) to the constructor. This approach automatically provides the configuration settings for the new queue by mirroring the settings of the queue passed in. Alternatively, you can manually set the properties in the instance to the states you want and call the parameterless constructor. - When the install utility is called, it looks for the . If it is `true`, the utility installs all the queues in the collection associated with your project installer. If is `false`, the utility ignores the project installer. + When the install utility is called, it looks for the . If it is `true`, the utility installs all the queues in the collection associated with your project installer. If is `false`, the utility ignores the project installer. - You modify other properties of a instance either before or after adding the instance to the collection of your project installer. For example, a queue's must be set before the install utility executes. + You modify other properties of a instance either before or after adding the instance to the collection of your project installer. For example, a queue's must be set before the install utility executes. - Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process and calls if the installation did not throw an exception. It backs out failures, if necessary, by calling for the object that generated the exception. + Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process and calls if the installation did not throw an exception. It backs out failures, if necessary, by calling for the object that generated the exception. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information is continuously updated as each instance is installed by the utility. It is not usually necessary for your code to explicitly modify the state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information is continuously updated as each instance is installed by the utility. It is not usually necessary for your code to explicitly modify the state information. ]]> @@ -122,7 +122,7 @@ for the message. Otherwise, there is no indication that the message was rejected, so the message can be lost unless you send it to the dead-letter queue. + When a non-authenticated message is sent to a queue that accepts only authenticated messages, the message is rejected. The sending application can request notification of a message rejection by setting the for the message. Otherwise, there is no indication that the message was rejected, so the message can be lost unless you send it to the dead-letter queue. ]]> @@ -158,9 +158,9 @@ is used for routing the queue's messages over the network. Use the to give the messages sent to the queue a higher or lower priority than that for messages sent to other queues. When a queue's base priority is set, all the messages sent to it are given a higher priority than that of the messages sent to queues with a lower base priority. The queue's base priority has no effect on the order of the messages in the queue or on how messages are read from the queue. + The is used for routing the queue's messages over the network. Use the to give the messages sent to the queue a higher or lower priority than that for messages sent to other queues. When a queue's base priority is set, all the messages sent to it are given a higher priority than that of the messages sent to queues with a lower base priority. The queue's base priority has no effect on the order of the messages in the queue or on how messages are read from the queue. - The applies only to public queues that are accessed through the domain controller (in other words, using the public format name). The base priority of private queues and of directly accessed public queues is always zero. + The applies only to public queues that are accessed through the domain controller (in other words, using the public format name). The base priority of private queues and of directly accessed public queues is always zero. ]]> @@ -204,9 +204,9 @@ can be a null reference. You can also define a new category. + The queue category enables an application to categorize associated queues according to the way they are used. The can be a null reference. You can also define a new category. - The property provides access to the Message Queuing type identifier property, which is associated with a particular queue and is read/write. You can use the method to create a category value that is guaranteed to be unique across all values. However, it is necessary only for the category value to be distinct from other categories, not from all other values. For example, you can set the for one group of queues to {00000000-0000-0000-0000-000000000001} and the for another group to {00000000-0000-0000-0000-000000000002}. + The property provides access to the Message Queuing type identifier property, which is associated with a particular queue and is read/write. You can use the method to create a category value that is guaranteed to be unique across all values. However, it is necessary only for the category value to be distinct from other categories, not from all other values. For example, you can set the for one group of queues to {00000000-0000-0000-0000-000000000001} and the for another group to {00000000-0000-0000-0000-000000000002}. ]]> @@ -239,11 +239,11 @@ from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. + Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. + After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility commits each instance. Usually, it is not necessary for your code to explicitly modify this state information. When the queue has been cleared, posts a log entry to the `savedState` that is associated with the installation. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility commits each instance. Usually, it is not necessary for your code to explicitly modify this state information. When the queue has been cleared, posts a log entry to the `savedState` that is associated with the installation. ]]> @@ -279,9 +279,9 @@ from within your code; they are generally called only by the installutil.exe installation utility. is used by the installation utility to set the property values for the to the values of an existing . + Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. is used by the installation utility to set the property values for the to the values of an existing . - If the of the that is passed in is an empty string (""), you must set the property to a non-empty value before the installer executes. + If the of the that is passed in is an empty string (""), you must set the property to a non-empty value before the installer executes. ]]> @@ -318,7 +318,7 @@ of a message is encrypted. Other properties, such as the , are not encrypted. + When encryption is specified, only the of a message is encrypted. Other properties, such as the , are not encrypted. ]]> @@ -351,16 +351,16 @@ method writes message queue information to the registry, and associates the instance with a queue that is located at the path specified by the property. If the queue does not already exist, creates a transactional queue. sets the new or existing queue properties to those that you have specified in the . If the queue already exists, its properties are reset to those of the . If the existing queue is not transactional, it is deleted and then recreated as a transactional queue. + The method writes message queue information to the registry, and associates the instance with a queue that is located at the path specified by the property. If the queue does not already exist, creates a transactional queue. sets the new or existing queue properties to those that you have specified in the . If the queue already exists, its properties are reset to those of the . If the existing queue is not transactional, it is deleted and then recreated as a transactional queue. > [!CAUTION] > If it is necessary to recreate the queue, messages in the queue will be lost. - Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process to write registry information that is associated with the message queue being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. + Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process to write registry information that is associated with the message queue being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. + After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the utility installs each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the utility installs each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -399,7 +399,7 @@ returns `true` only if this installer and the installer specified by the `otherInstaller` parameter are of the same type. + Typically, returns `true` only if this installer and the installer specified by the `otherInstaller` parameter are of the same type. ]]> @@ -620,14 +620,14 @@ Use "." for the local computer. - You can also use the or of a Message Queuing application object to describe the queue path. The following table shows the proper syntax for each type of reference. + You can also use the or of a Message Queuing application object to describe the queue path. The following table shows the proper syntax for each type of reference. |Reference|Syntax| |---------------|------------| |Format name|FormatName:[ *format name* ]| |Label|Label:[ *label* ]| - If you are working offline, you must use the format name to define the queue . If you do not, the application will throw an exception, because the primary domain controller is unavailable to resolve the into the . + If you are working offline, you must use the format name to define the queue . If you do not, the application will throw an exception, because the primary domain controller is unavailable to resolve the into the . ]]> @@ -754,11 +754,11 @@ method undoes the effects of the method. is called if the installation of any component in the installation project fails. The method creates or sets the properties for a queue. either deletes the queue or resets the properties of a pre-existing queue to their pre-installation values. + The method undoes the effects of the method. is called if the installation of any component in the installation project fails. The method creates or sets the properties for a queue. either deletes the queue or resets the properties of a pre-existing queue to their pre-installation values. - Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility. The utility automatically calls the method after an installation failure to undo any changes that the installation process has already made. + Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility. The utility automatically calls the method after an installation failure to undo any changes that the installation process has already made. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility rolls back each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility rolls back each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -832,11 +832,11 @@ is `Remove`, also deletes the queue associated with the . + If the is `Remove`, also deletes the queue associated with the . - Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility (in uninstall mode). The utility automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the MessageQueue being uninstalled. + Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility (in uninstall mode). The utility automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the MessageQueue being uninstalled. - An application's uninstall routine uses the project installer's to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility uninstalls each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's uninstall routine uses the project installer's to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility uninstalls each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> diff --git a/xml/System.Messaging/MessageQueuePermissionAttribute.xml b/xml/System.Messaging/MessageQueuePermissionAttribute.xml index 91f5f896f39..d282895ce2f 100644 --- a/xml/System.Messaging/MessageQueuePermissionAttribute.xml +++ b/xml/System.Messaging/MessageQueuePermissionAttribute.xml @@ -143,7 +143,7 @@ . + The following code example calls . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet7"::: diff --git a/xml/System.Messaging/MessageQueuePermissionEntryCollection.xml b/xml/System.Messaging/MessageQueuePermissionEntryCollection.xml index 4053268b0a2..1a4f113d649 100644 --- a/xml/System.Messaging/MessageQueuePermissionEntryCollection.xml +++ b/xml/System.Messaging/MessageQueuePermissionEntryCollection.xml @@ -24,14 +24,14 @@ Contains a strongly typed collection of objects. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet0"::: + ]]> @@ -66,14 +66,14 @@ Adds a specified to this collection. The zero-based index of the added . - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet1"::: + ]]> @@ -111,14 +111,14 @@ An array of type objects that contains the permission entries to add. Appends a set of specified permission entries to this collection. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet2"::: + ]]> @@ -147,14 +147,14 @@ A that contains the permission entries to add. Appends a set of specified permission entries to this collection. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet3"::: + ]]> @@ -185,14 +185,14 @@ if the specified belongs to this collection; otherwise, . - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet4"::: + ]]> @@ -223,14 +223,14 @@ The zero-based index at which to begin copying the permission entries. Copies the permission entries from this collection to an array, starting at a particular index of the array. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet5"::: + ]]> @@ -260,14 +260,14 @@ Determines the index of a specified permission entry in this collection. The zero-based index of the specified permission entry, or -1 if the permission entry was not found in the collection. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet6"::: + ]]> @@ -298,14 +298,14 @@ The permission entry to insert into this collection. Inserts a permission entry into this collection at a specified index. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet7"::: + ]]> @@ -335,14 +335,14 @@ Gets or sets the object at a specified index. The that exists at the specified index. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet8"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet8"::: + ]]> @@ -480,14 +480,14 @@ The permission entry to remove. Removes a specified permission entry from this collection. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntryCollection/cpp/class1.cpp" id="Snippet9"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet9"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntryCollection/Overview/class1.cs" id="Snippet9"::: + ]]> diff --git a/xml/System.Messaging/MessageQueueTransaction.xml b/xml/System.Messaging/MessageQueueTransaction.xml index cbea40a5896..ba786d94561 100644 --- a/xml/System.Messaging/MessageQueueTransaction.xml +++ b/xml/System.Messaging/MessageQueueTransaction.xml @@ -25,13 +25,13 @@ class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. + To send or receive a message as part of a transaction, you can use the class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. - In addition to the method, you can receive messages with a specified identifier or specified correlation identifier. See the and methods for more information about selectively receiving messages from transactional queues. + In addition to the method, you can receive messages with a specified identifier or specified correlation identifier. See the and methods for more information about selectively receiving messages from transactional queues. Messages sent to transactional queues are removed if the transaction is committed. Similarly, messages received from transactional queues are returned to the queue if the transaction is rolled back. - If you instantiate a and pass it to an applicable overload of the method or method to send a message to a non-transactional queue or receive a message from a non-transactional queue, the method throws an exception that indicates "Wrong Transaction Usage." + If you instantiate a and pass it to an applicable overload of the method or method to send a message to a non-transactional queue or receive a message from a non-transactional queue, the method throws an exception that indicates "Wrong Transaction Usage." is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -97,11 +97,11 @@ marks the unsuccessful completion of a process begun at a call to . + marks the unsuccessful completion of a process begun at a call to . - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. - rolls back the entire transaction. This includes all messages sent or received after the call to . + rolls back the entire transaction. This includes all messages sent or received after the call to . ]]> @@ -136,9 +136,9 @@ marks the start of processing that will be committed or rolled back, depending on the success of the transaction. If an exception occurs during processing, the entire transaction is rolled back. This includes all messages sent or received after the call to . + marks the start of processing that will be committed or rolled back, depending on the success of the transaction. If an exception occurs during processing, the entire transaction is rolled back. This includes all messages sent or received after the call to . - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. ]]> @@ -173,9 +173,9 @@ marks the successful completion of processing begun at a call to . If an exception occurs between the call the and the call to , the entire transaction is rolled back. This includes all messages sent or received after the call to . + marks the successful completion of processing begun at a call to . If an exception occurs between the call the and the call to , the entire transaction is rolled back. This includes all messages sent or received after the call to . - Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. + Typically, one makes a call to within a `Try...Catch` exception-handling block, putting a call to in the `Try` clause, and a call to in the `Catch` clause. ]]> @@ -222,9 +222,9 @@ allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + Calling allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - Any pending internal transactions are rolled back by . + Any pending internal transactions are rolled back by . ]]> @@ -258,7 +258,7 @@ method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. + This method is called by the public method and the method, if it has been overridden. `Dispose` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -296,7 +296,7 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v%3dvs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -328,7 +328,7 @@ class has been created, the is set by the constructor to `Initialized`. After a call to but before a call to or , the is `Pending`. + When an instance of the class has been created, the is set by the constructor to `Initialized`. After a call to but before a call to or , the is `Pending`. ]]> diff --git a/xml/System.Messaging/MessageQueueTransactionStatus.xml b/xml/System.Messaging/MessageQueueTransactionStatus.xml index 2cb7f55de07..a2f67b35b75 100644 --- a/xml/System.Messaging/MessageQueueTransactionStatus.xml +++ b/xml/System.Messaging/MessageQueueTransactionStatus.xml @@ -20,7 +20,7 @@ class has been created, its property is set by the constructor to `Initialized`. After a transaction has begun, but before it is committed or rolled back, the is `Pending`. + When an instance of the class has been created, its property is set by the constructor to `Initialized`. After a transaction has begun, but before it is committed or rolled back, the is `Pending`. ]]> diff --git a/xml/System.Messaging/MessageQueueTransactionType.xml b/xml/System.Messaging/MessageQueueTransactionType.xml index b96c57ddfab..50f0245bd16 100644 --- a/xml/System.Messaging/MessageQueueTransactionType.xml +++ b/xml/System.Messaging/MessageQueueTransactionType.xml @@ -17,15 +17,15 @@ Specifies the type of a Message Queuing transaction. - class's or methods (including and ) that takes a `transactionType` parameter, you can specify how you are interacting with the queue. `Automatic` enables you to send and receive from external transactions (such as when you are interacting with database applications), while `Single` is used for single internal Message Queuing transactions. - - `None` enables you to receive a message from a transactional queue outside of a transaction or send a transactional message to a non-transactional queue. This is useful, for example, when routing several messages sent within a single transaction. - - If you want to send or receive a message using an internal Message Queuing transaction but not a single internal transaction, create an instance of the class and pass it into an overload of the or methods that takes a `transaction` parameter rather than one that takes a `transactionType` parameter. - + class's or methods (including and ) that takes a `transactionType` parameter, you can specify how you are interacting with the queue. `Automatic` enables you to send and receive from external transactions (such as when you are interacting with database applications), while `Single` is used for single internal Message Queuing transactions. + + `None` enables you to receive a message from a transactional queue outside of a transaction or send a transactional message to a non-transactional queue. This is useful, for example, when routing several messages sent within a single transaction. + + If you want to send or receive a message using an internal Message Queuing transaction but not a single internal transaction, create an instance of the class and pass it into an overload of the or methods that takes a `transaction` parameter rather than one that takes a `transactionType` parameter. + ]]> diff --git a/xml/System.Messaging/MessageType.xml b/xml/System.Messaging/MessageType.xml index 25da18c08c9..294e12b4abc 100644 --- a/xml/System.Messaging/MessageType.xml +++ b/xml/System.Messaging/MessageType.xml @@ -20,7 +20,7 @@ class or any overload of the method. + Typical (`Normal` type) messages are those that you send to a queue using either the class or any overload of the method. Message Queuing generates acknowledgment messages whenever the sending application requests one. If you send a message using the class, you can use its property to specify the types of acknowledgments to receive. For example, Message Queuing can generate positive or negative messages to indicate that the original message arrived or was read. Message Queuing returns the appropriate acknowledgment message to the administration queue specified by the sending application. When you receive or peek an acknowledgment message using a , its property indicates the reason Message Queuing sent the acknowledgment. diff --git a/xml/System.Messaging/MessagingDescriptionAttribute.xml b/xml/System.Messaging/MessagingDescriptionAttribute.xml index ad16a310618..65dc99931c8 100644 --- a/xml/System.Messaging/MessagingDescriptionAttribute.xml +++ b/xml/System.Messaging/MessagingDescriptionAttribute.xml @@ -60,7 +60,7 @@ constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies + The description you specify in the constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies ]]> diff --git a/xml/System.Messaging/PeekAction.xml b/xml/System.Messaging/PeekAction.xml index a796cb534a0..71785b9ecc7 100644 --- a/xml/System.Messaging/PeekAction.xml +++ b/xml/System.Messaging/PeekAction.xml @@ -16,11 +16,11 @@ Indicates whether to peek the current message in a queue, or the next message. - enumeration with and to indicate whether you want to peek at the current message in the queue, or the next message. - + enumeration with and to indicate whether you want to peek at the current message in the queue, or the next message. + ]]> diff --git a/xml/System.Messaging/PeekCompletedEventArgs.xml b/xml/System.Messaging/PeekCompletedEventArgs.xml index 860207defb4..8baf89926fb 100644 --- a/xml/System.Messaging/PeekCompletedEventArgs.xml +++ b/xml/System.Messaging/PeekCompletedEventArgs.xml @@ -21,11 +21,11 @@ to begin the asynchronous processing. When a message is peeked, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. + When you use event notification to peek (read without removing) messages asynchronously from the queue, you must create a method that handles your message processing. Your code must call to begin the asynchronous processing. When a message is peeked, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . @@ -70,9 +70,9 @@ identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. + identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. - When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. + When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. ]]> @@ -107,7 +107,7 @@ ## Remarks The property provides a means for retrieving the message that initiated the end of the asynchronous peek operation. - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. ]]> diff --git a/xml/System.Messaging/ReceiveCompletedEventArgs.xml b/xml/System.Messaging/ReceiveCompletedEventArgs.xml index c9c9f01862d..b94c7ff329a 100644 --- a/xml/System.Messaging/ReceiveCompletedEventArgs.xml +++ b/xml/System.Messaging/ReceiveCompletedEventArgs.xml @@ -21,11 +21,11 @@ to begin the asynchronous processing. When a message is received, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. + When you use event notification to receive messages asynchronously from the queue, you must create a method that handles your message processing. Your code must call to begin the asynchronous processing. When a message is received, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . @@ -70,9 +70,9 @@ identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. + identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. - When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. + When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. ]]> @@ -107,7 +107,7 @@ ## Remarks The property provides a means for retrieving the message that initiated the end of the asynchronous receive operation. - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. ]]> diff --git a/xml/System.Messaging/SecurityContext.xml b/xml/System.Messaging/SecurityContext.xml index 7c27bc921aa..8483f1a4d84 100644 --- a/xml/System.Messaging/SecurityContext.xml +++ b/xml/System.Messaging/SecurityContext.xml @@ -21,21 +21,21 @@ Represents the security context for a message in a queue. - before sending a message to a remote queue to ensure that the current user's credentials are used to gain access to the queue. However, the suggested best practice is to: - -1. Make the queue an authenticated queue. - -2. Run the ASP.NET application as a domain identity and authorize that application to write to the queue. - -3. Do not impersonate the user when using the queue. Instead, get the caller's identity and either perform authorization checking in the ASP.NET application or include the caller's identity as part of the message and perform authorization checking in the receiver application. - + before sending a message to a remote queue to ensure that the current user's credentials are used to gain access to the queue. However, the suggested best practice is to: + +1. Make the queue an authenticated queue. + +2. Run the ASP.NET application as a domain identity and authorize that application to write to the queue. + +3. Do not impersonate the user when using the queue. Instead, get the caller's identity and either perform authorization checking in the ASP.NET application or include the caller's identity as part of the message and perform authorization checking in the receiver application. + ]]> diff --git a/xml/System.Messaging/Trustee.xml b/xml/System.Messaging/Trustee.xml index 22d473759a9..f54a7293359 100644 --- a/xml/System.Messaging/Trustee.xml +++ b/xml/System.Messaging/Trustee.xml @@ -21,9 +21,9 @@ member (either directly or using the constructor) to specify whether the trustee is a user, computer, or other type. If you do not specify the trustee type before setting permissions for the trustee, the type defaults to `Unknown`. + The trustee is the entity to whom you are granting or denying access rights when you create an access control entry. Set the member (either directly or using the constructor) to specify whether the trustee is a user, computer, or other type. If you do not specify the trustee type before setting permissions for the trustee, the type defaults to `Unknown`. - You must specify a value for the property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. + You must specify a value for the property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. ]]> @@ -61,7 +61,7 @@ property before using the instance to set permissions. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. + You must specify a value for the property before using the instance to set permissions. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. ]]> @@ -198,11 +198,11 @@ property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. + You must specify a value for the property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. - If you do not specify a value for the property, the account you identify in the property is looked up on the local computer. If you do specify a , the account is looked up on the computer you specify. + If you do not specify a value for the property, the account you identify in the property is looked up on the local computer. If you do specify a , the account is looked up on the computer you specify. - If you are not connected to the network (for example, if you are in workgroup mode), the property can be any local user or group. In this case, you should not specify any value for , as workgroup mode is local by definition. + If you are not connected to the network (for example, if you are in workgroup mode), the property can be any local user or group. In this case, you should not specify any value for , as workgroup mode is local by definition. ]]> @@ -234,7 +234,7 @@ before you use this instance of to set permissions, but is optional. If you leave `null`, the local computer is used to look up the account you specify in the property. + You must specify a value for before you use this instance of to set permissions, but is optional. If you leave `null`, the local computer is used to look up the account you specify in the property. ]]> @@ -265,9 +265,9 @@ indicates what type of account the trustee is associated with on the domain controller or on the local computer. This can be, for example, a user account, a group account, or a computer account. + The indicates what type of account the trustee is associated with on the domain controller or on the local computer. This can be, for example, a user account, a group account, or a computer account. - If you are specifying a predefined group name for the property, such as Everyone, the is `Group`, rather than `Alias`. + If you are specifying a predefined group name for the property, such as Everyone, the is `Group`, rather than `Alias`. ]]> diff --git a/xml/System.Messaging/TrusteeType.xml b/xml/System.Messaging/TrusteeType.xml index 7ad6b503b70..99abb657bf0 100644 --- a/xml/System.Messaging/TrusteeType.xml +++ b/xml/System.Messaging/TrusteeType.xml @@ -17,11 +17,11 @@ Specifies the type of a trustee. - member of a . - + member of a . + ]]> diff --git a/xml/System.Messaging/XmlMessageFormatter.xml b/xml/System.Messaging/XmlMessageFormatter.xml index 5258d479ab3..45d85e95a21 100644 --- a/xml/System.Messaging/XmlMessageFormatter.xml +++ b/xml/System.Messaging/XmlMessageFormatter.xml @@ -30,13 +30,13 @@ ## Remarks The is the default formatter that an instance of uses to serialize messages written to the queue. When you create an instance of , an instance of is created for you and associated with the . You can specify a different formatter by creating it in your code and assigning it to the property of your . - A queue's default instance can be used to write to the queue, but it cannot be used to read from the queue until you set either the or property on the formatter. You can either set one or both of these values on the default formatter instance, or you can create a new instance of the formatter and set the values automatically by passing them as arguments into the appropriate constructor. + A queue's default instance can be used to write to the queue, but it cannot be used to read from the queue until you set either the or property on the formatter. You can either set one or both of these values on the default formatter instance, or you can create a new instance of the formatter and set the values automatically by passing them as arguments into the appropriate constructor. - When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. + When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. - The and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. + The and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. Only one of the two properties needs to be set when reading from the queue, but you can set both. The set of types is the combined set from the two properties. The decision of which property to use is specific to your application. If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown when the message is read. @@ -112,7 +112,7 @@ ## Remarks This overload of the constructor is used most frequently when writing to the queue, as target types are not required when writing. - To read a message from a queue using an instance of created using this constructor, you must set the or properties so the formatter knows what types to attempt to deserialize. + To read a message from a queue using an instance of created using this constructor, you must set the or properties so the formatter knows what types to attempt to deserialize. When you create a new , a default instance is created, without the target types set. As with a formatter created using this constructor, you must set target types for that formatter instance if you want to read from the queue. @@ -146,11 +146,11 @@ ## Remarks The constructors with target type parameters are most frequently used when reading from the queue. When writing, it is not necessary to specify target types. - This overload of the constructor sets the property to the array values passed in through the `targetTypeNames` parameter. Setting this property enables a using this instance to read messages containing objects of given types. + This overload of the constructor sets the property to the array values passed in through the `targetTypeNames` parameter. Setting this property enables a using this instance to read messages containing objects of given types. - Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. + Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. Only one of the two properties needs to be set when reading from the queue, but you can set both. The set of types is the combined set from the two properties. The decision of which one to use is specific to your application. If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown at read time. @@ -192,17 +192,17 @@ ## Remarks The constructors with target type parameters are most frequently used when reading from the queue. When writing, it is not necessary to specify target types. - This overload of the constructor sets the property to the array values passed in through the `targetTypes` parameter. Setting this property enables a using this instance to read messages containing objects of the given types. + This overload of the constructor sets the property to the array values passed in through the `targetTypes` parameter. Setting this property enables a using this instance to read messages containing objects of the given types. - Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. + Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. Only one of the two properties needs to be set when reading from the queue, but you can set both. The set of types is the combined set from the two properties. The decision of which one to use is specific to your application. If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown at read time. - When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. + When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. - When using , you can add each object (for example, `MyClass`) to the list in a way demonstrated by the following C# code. + When using , you can add each object (for example, `MyClass`) to the list in a way demonstrated by the following C# code. ``` TargetTypes = new Type[]{typeof(MyClass)} @@ -245,13 +245,13 @@ TargetTypes = new Type[]{typeof(MyClass)} is called, the formatter attempts to determine if the contents of the message are something it can deserialize. The formatter can only deserialize the message if the type in the message body has the same schema as one of the types in the array represented by the and properties. returns `false` under the following two circumstances: + When is called, the formatter attempts to determine if the contents of the message are something it can deserialize. The formatter can only deserialize the message if the type in the message body has the same schema as one of the types in the array represented by the and properties. returns `false` under the following two circumstances: - The message was not formatted using the . -- The schema of the message body is not among those listed in either the or property. +- The schema of the message body is not among those listed in either the or property. - The and properties tell the formatter what types of objects it must be able to deserialize. If any type is missing from the list, yet is found within the message, returns `false`. + The and properties tell the formatter what types of objects it must be able to deserialize. If any type is missing from the list, yet is found within the message, returns `false`. ]]> @@ -329,9 +329,9 @@ TargetTypes = new Type[]{typeof(MyClass)} and properties tell the formatter what schemas to attempt to match when deserializing a message. One of these properties must be set before the message can be deserialized. + Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. One of these properties must be set before the message can be deserialized. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. The target types do not have to be specified in order to write to the queue. @@ -380,15 +380,15 @@ TargetTypes = new Type[]{typeof(MyClass)} and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. + Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. Only one of the two properties needs to be set when reading from the queue, but you can set both. The set of types is the combined set from the two properties. The decision of which property to use is specific to your application. If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown when the message is read. - requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. + requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. - The target types are only required when reading from the queue. The and properties do not need to be set to write to the queue. + The target types are only required when reading from the queue. The and properties do not need to be set to write to the queue. ]]> @@ -436,17 +436,17 @@ TargetTypes = new Type[]{typeof(MyClass)} and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. + Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. - The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. + The instance serialized in the message body must comply with one of the schemas represented in the type array. When you read the message using the method, the method creates an object of the type that corresponds to the schema identified and reads the message body into it. Only one of the two properties needs to be set when reading from the queue, but you can set both. The set of types is the combined set from the two properties. The decision of which property to use is specific to your application. If the message body contains a type whose schema does not match any of the types in the array for either property, an exception will be thrown when the message is read. - The target types are only required when reading from the queue. The and properties do not need to be set to write to the queue. + The target types are only required when reading from the queue. The and properties do not need to be set to write to the queue. - When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. + When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. - When using , you can add each object (for example, `MyClass`) to the list in a way demonstrated by the C# code `TargetTypes = new Type[]{typeof(MyClass), typeof (MyOtherClass)};`. + When using , you can add each object (for example, `MyClass`) to the list in a way demonstrated by the C# code `TargetTypes = new Type[]{typeof(MyClass), typeof (MyOtherClass)};`. @@ -497,7 +497,7 @@ TargetTypes = new Type[]{typeof(MyClass)} or property is used by the formatter only when deserializing a message. + The target types need not be specified to write to the queue as they must be when reading. The or property is used by the formatter only when deserializing a message. The makes use of the class, which defines what can be serialized. Only public fields and public properties can be serialized. Structures, structures with arrays, and arrays of structures are all serializable, as long as they do not use the encoded style with the SOAP protocol. diff --git a/xml/System.Net.Cache/RequestCachePolicy.xml b/xml/System.Net.Cache/RequestCachePolicy.xml index 53717f62cc5..f14a8ea62a0 100644 --- a/xml/System.Net.Cache/RequestCachePolicy.xml +++ b/xml/System.Net.Cache/RequestCachePolicy.xml @@ -57,7 +57,7 @@ ## Examples - The following code example creates a policy with set to , and uses it to set the cache policy of a . + The following code example creates a policy with set to , and uses it to set the cache policy of a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet13"::: @@ -183,7 +183,7 @@ ## Examples - The following code example creates a policy with set to .and uses it to set the cache policy of a . + The following code example creates a policy with set to .and uses it to set the cache policy of a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet13"::: @@ -243,7 +243,7 @@ ## Remarks Applications typically use as their cache policy level. Using the level, the effective cache policy is determined by the current cache policy and the age of the content in the cache. The property, if not `null`, determines the cache policy in effect for a request. - The default policy for the application domain can be set using the or the application or machine configuration file. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). + The default policy for the application domain can be set using the or the application or machine configuration file. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). diff --git a/xml/System.Net.Configuration/ConnectionManagementElement.xml b/xml/System.Net.Configuration/ConnectionManagementElement.xml index 8f380a0a386..9ad4458a5c0 100644 --- a/xml/System.Net.Configuration/ConnectionManagementElement.xml +++ b/xml/System.Net.Configuration/ConnectionManagementElement.xml @@ -165,7 +165,7 @@ ## Remarks This property specifies how many simultaneous connections are allowed between the local computer and the remote computer. The remote computer is specified using the property. - The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. + The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. ]]> diff --git a/xml/System.Net.Configuration/DefaultProxySection.xml b/xml/System.Net.Configuration/DefaultProxySection.xml index c35be1fb4d3..639e1d78054 100644 --- a/xml/System.Net.Configuration/DefaultProxySection.xml +++ b/xml/System.Net.Configuration/DefaultProxySection.xml @@ -17,23 +17,23 @@ Represents the configuration section for Web proxy server usage. This class cannot be inherited. - and classes. The following table describes the configuration elements contained in the configuration section. - -|Element|Description| -|-------------|-----------------| -||Identifies the Web proxy server to use.| -||Identifies resources that are not retrieved using the proxy server.| -||Identifies a custom implementation.| - - This class provides programmatic access to information that can be stored in configuration files. - - The settings apply only to the default proxy server. - + and classes. The following table describes the configuration elements contained in the configuration section. + +|Element|Description| +|-------------|-----------------| +||Identifies the Web proxy server to use.| +||Identifies resources that are not retrieved using the proxy server.| +||Identifies a custom implementation.| + + This class provides programmatic access to information that can be stored in configuration files. + + The settings apply only to the default proxy server. + ]]> @@ -86,11 +86,11 @@ Gets the collection of resources that are not obtained using the Web proxy server. A that contains the addresses of resources that bypass the Web proxy server. - returned by this property contains one for each resource that bypasses the Web Proxy server. - + returned by this property contains one for each resource that bypasses the Web Proxy server. + ]]> @@ -152,11 +152,11 @@ Gets the type information for a custom Web proxy implementation. The type information for a custom Web proxy implementation. - returned by this property identifies the type, assembly, and version of a custom implementation. - + returned by this property identifies the type, assembly, and version of a custom implementation. + ]]> @@ -239,11 +239,11 @@ Gets the URI that identifies the Web proxy server to use. The URI that identifies the Web proxy server. - returned by this property identifies the Web proxy server to use for resources that are not in the collection. - + returned by this property identifies the Web proxy server to use for resources that are not in the collection. + ]]> diff --git a/xml/System.Net.Configuration/HttpCachePolicyElement.xml b/xml/System.Net.Configuration/HttpCachePolicyElement.xml index 6fddaabe932..48b485a650f 100644 --- a/xml/System.Net.Configuration/HttpCachePolicyElement.xml +++ b/xml/System.Net.Configuration/HttpCachePolicyElement.xml @@ -51,7 +51,7 @@ , , , and properties to the collection. + This constructor adds the , , , and properties to the collection. ]]> diff --git a/xml/System.Net.Configuration/HttpListenerTimeoutsElement.xml b/xml/System.Net.Configuration/HttpListenerTimeoutsElement.xml index e264bab6afe..a1f8f0294ce 100644 --- a/xml/System.Net.Configuration/HttpListenerTimeoutsElement.xml +++ b/xml/System.Net.Configuration/HttpListenerTimeoutsElement.xml @@ -16,11 +16,11 @@ Represents the timeouts element in the configuration file. This class cannot be inherited. - instance. - + instance. + ]]> @@ -70,11 +70,11 @@ Gets the time, in seconds, allowed for the to drain the entity body on a Keep-Alive connection. The time, in seconds, allowed for the to drain the entity body on a Keep-Alive connection. - starts draining the remainder of the entity body to reach another potentially pipelined request from the client. If the time to drain the remaining entity body exceeds the allowed period the connection is timed out. - + starts draining the remainder of the entity body to reach another potentially pipelined request from the client. If the time to drain the remaining entity body exceeds the allowed period the connection is timed out. + ]]> @@ -108,11 +108,11 @@ Gets the time, in seconds, allowed for the request entity body to arrive. The time, in seconds, allowed for the request entity body to arrive. - turns on this timer when the request has an entity body. The timer expiration is initially set to the configured value. When the receives additional data indications on the request, it resets the timer to give the connection another interval. - + turns on this timer when the request has an entity body. The timer expiration is initially set to the configured value. When the receives additional data indications on the request, it resets the timer to give the connection another interval. + ]]> @@ -146,13 +146,13 @@ Gets the time, in seconds, allowed for the to parse the request header. The time, in seconds, allowed for the to parse the request header. - . - - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. - + . + + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + ]]> @@ -186,13 +186,13 @@ Gets the time, in seconds, allowed for an idle connection. The time, in seconds, allowed for an idle connection. - . - - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. - + . + + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + ]]> diff --git a/xml/System.Net.Configuration/HttpWebRequestElement.xml b/xml/System.Net.Configuration/HttpWebRequestElement.xml index e59b4eeaf50..b4e392b5bcd 100644 --- a/xml/System.Net.Configuration/HttpWebRequestElement.xml +++ b/xml/System.Net.Configuration/HttpWebRequestElement.xml @@ -51,7 +51,7 @@ object that represents the to the collection. + This constructor adds a object that represents the to the collection. ]]> diff --git a/xml/System.Net.Configuration/Ipv6Element.xml b/xml/System.Net.Configuration/Ipv6Element.xml index 5a2f783d6c4..87cd8d9de82 100644 --- a/xml/System.Net.Configuration/Ipv6Element.xml +++ b/xml/System.Net.Configuration/Ipv6Element.xml @@ -50,7 +50,7 @@ property to the collection. + This constructor adds the property to the collection. ]]> diff --git a/xml/System.Net.Configuration/ModuleElement.xml b/xml/System.Net.Configuration/ModuleElement.xml index 3a291f30017..4e05ca4566b 100644 --- a/xml/System.Net.Configuration/ModuleElement.xml +++ b/xml/System.Net.Configuration/ModuleElement.xml @@ -51,7 +51,7 @@ object for the property to the collection. + This constructor adds a object for the property to the collection. ]]> diff --git a/xml/System.Net.Configuration/ServicePointManagerElement.xml b/xml/System.Net.Configuration/ServicePointManagerElement.xml index c0e14a952db..c8972f8c09d 100644 --- a/xml/System.Net.Configuration/ServicePointManagerElement.xml +++ b/xml/System.Net.Configuration/ServicePointManagerElement.xml @@ -266,7 +266,7 @@ ## Remarks When this property is set to `true`, client requests that use the `POST` method expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. - For additional information, see . + For additional information, see . ]]> diff --git a/xml/System.Net.Configuration/SmtpNetworkElement.xml b/xml/System.Net.Configuration/SmtpNetworkElement.xml index c5b7dd6782a..4138c9de6d1 100644 --- a/xml/System.Net.Configuration/SmtpNetworkElement.xml +++ b/xml/System.Net.Configuration/SmtpNetworkElement.xml @@ -236,7 +236,7 @@ takes precedence over setting and . and are used only if is set to `false`. + Setting takes precedence over setting and . and are used only if is set to `false`. ]]> @@ -406,7 +406,7 @@ takes precedence over setting and . and are used only if is set to `false`. + Setting takes precedence over setting and . and are used only if is set to `false`. ]]> diff --git a/xml/System.Net.Configuration/SmtpSection.xml b/xml/System.Net.Configuration/SmtpSection.xml index b71c766882c..3df89ccfba5 100644 --- a/xml/System.Net.Configuration/SmtpSection.xml +++ b/xml/System.Net.Configuration/SmtpSection.xml @@ -17,11 +17,11 @@ Represents the SMTP section in the configuration file. - namespace. - + namespace. + ]]> @@ -70,8 +70,8 @@ Gets or sets the delivery format to use for sending outgoing email using the Simple Mail Transport Protocol (SMTP). - Returns . - + Returns . + The delivery format to use for sending outgoing email using SMTP. To be added. @@ -104,11 +104,11 @@ Gets or sets the Simple Mail Transport Protocol (SMTP) delivery method. The default delivery method is . A string that represents the SMTP delivery method. - , , and . These values have configurable sub-items and have a corresponding section in the `System.Net` configuration file. All the sections are camel-cased, to allow the users to match the delivery method with their corresponding section names. - + , , and . These values have configurable sub-items and have a corresponding section in the `System.Net` configuration file. All the sections are camel-cased, to allow the users to match the delivery method with their corresponding section names. + ]]> @@ -168,8 +168,8 @@ Gets the configuration element that controls the network settings used by the Simple Mail Transport Protocol (SMTP). file.. - A object. - + A object. + The configuration element that controls the network settings used by SMTP. To be added. @@ -230,11 +230,11 @@ Gets the pickup directory that will be used by the SMTP client. A object that specifies the pickup directory folder. - will be used as the SMTP pickup directory. If the SMTP client is unable to write to the pickup directory location an I/O exception is thrown by . The directory will not be created if it does not exist. The credentials of the currently running thread or process will be used to access the directory. - + will be used as the SMTP pickup directory. If the SMTP client is unable to write to the pickup directory location an I/O exception is thrown by . The directory will not be created if it does not exist. The credentials of the currently running thread or process will be used to access the directory. + ]]> diff --git a/xml/System.Net.Configuration/SocketElement.xml b/xml/System.Net.Configuration/SocketElement.xml index 695f1ed5dcf..f788b41f6a6 100644 --- a/xml/System.Net.Configuration/SocketElement.xml +++ b/xml/System.Net.Configuration/SocketElement.xml @@ -51,7 +51,7 @@ and properties to the collection. + This constructor adds the and properties to the collection. ]]> diff --git a/xml/System.Net.Configuration/WebRequestModuleElement.xml b/xml/System.Net.Configuration/WebRequestModuleElement.xml index aa3a6095938..8ac7fd23ae5 100644 --- a/xml/System.Net.Configuration/WebRequestModuleElement.xml +++ b/xml/System.Net.Configuration/WebRequestModuleElement.xml @@ -20,7 +20,7 @@ and classes, applications can request resources for any valid . Use this configuration element to specify a module that is registered to work with the overloads to create new requests. + Using the and classes, applications can request resources for any valid . Use this configuration element to specify a module that is registered to work with the overloads to create new requests. This class corresponds to the [<add> Element for webRequestModules (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/add-element-for-webrequestmodules-network-settings) configuration element. @@ -237,7 +237,7 @@ and classes, applications can request resources for any valid . Use this property to specify a type that is registered to work with the method to create new requests. + Using the and classes, applications can request resources for any valid . Use this property to specify a type that is registered to work with the method to create new requests. The .NET Framework version 2.0 provides Web request modules that create requests for resources with the following prefixes: diff --git a/xml/System.Net.Http.Headers/AuthenticationHeaderValue.xml b/xml/System.Net.Http.Headers/AuthenticationHeaderValue.xml index abc702ca84b..86f17efb51a 100644 --- a/xml/System.Net.Http.Headers/AuthenticationHeaderValue.xml +++ b/xml/System.Net.Http.Headers/AuthenticationHeaderValue.xml @@ -298,7 +298,7 @@ Authorization: Bearer ACCESS_TOKEN ## Remarks A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. - The method is suitable for use in hashing algorithms and data structures such as a hash table. + The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> diff --git a/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml b/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml index cbeb4ab42ba..d78d02d1990 100644 --- a/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml +++ b/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml @@ -231,7 +231,7 @@ ## Remarks A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. - The method is suitable for use in hashing algorithms and data structures such as a hash table. + The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> @@ -653,7 +653,7 @@ ## Remarks This property represents the "no-transform" directive in a cache-control header field on an HTTP request or HTTP response. - When the is set to `true`, intermediate caches or proxies must not change any aspect of the entity body. Implementors of intermediate caches and proxies have found it useful to convert the media type of certain entity bodies. A non-transparent proxy might, for example, convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. Serious operational problems occur, however, when these transformations are applied to entity bodies intended for certain kinds of applications. + When the is set to `true`, intermediate caches or proxies must not change any aspect of the entity body. Implementors of intermediate caches and proxies have found it useful to convert the media type of certain entity bodies. A non-transparent proxy might, for example, convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. Serious operational problems occur, however, when these transformations are applied to entity bodies intended for certain kinds of applications. ]]> diff --git a/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml b/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml index 9b3937729c6..3f93e6360a2 100644 --- a/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml @@ -386,7 +386,7 @@ property uses IETF RFC 5987 encoding. The and properties differ only in that uses the encoding defined in IETF RFC 5987, allowing the use of characters not present in the ISO-8859-1 character set. + The property uses IETF RFC 5987 encoding. The and properties differ only in that uses the encoding defined in IETF RFC 5987, allowing the use of characters not present in the ISO-8859-1 character set. ]]> diff --git a/xml/System.Net.Http.Headers/ContentRangeHeaderValue.xml b/xml/System.Net.Http.Headers/ContentRangeHeaderValue.xml index ca87c494614..285a83c66ed 100644 --- a/xml/System.Net.Http.Headers/ContentRangeHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ContentRangeHeaderValue.xml @@ -317,13 +317,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -712,11 +712,11 @@ This member is an explicit interface member implementation. It can be used only The range units used. A that contains range units. - diff --git a/xml/System.Net.Http.Headers/EntityTagHeaderValue.xml b/xml/System.Net.Http.Headers/EntityTagHeaderValue.xml index 7c37ee9f500..75f64db0aa0 100644 --- a/xml/System.Net.Http.Headers/EntityTagHeaderValue.xml +++ b/xml/System.Net.Http.Headers/EntityTagHeaderValue.xml @@ -57,11 +57,11 @@ Represents an entity-tag header value. - @@ -192,11 +192,11 @@ Gets the entity-tag header value. Returns . - @@ -289,13 +289,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/HttpHeaders.xml b/xml/System.Net.Http.Headers/HttpHeaders.xml index 7d521b79828..0a29348a88a 100644 --- a/xml/System.Net.Http.Headers/HttpHeaders.xml +++ b/xml/System.Net.Http.Headers/HttpHeaders.xml @@ -159,7 +159,7 @@ The header `values` will be parsed and validated. - If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. + If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. If the specified header is already present, `values` are added to the comma-separated list of values associated with the header. @@ -232,7 +232,7 @@ The header value format is invalid for this header name, or the header does not The header `values` will be parsed and validated. - If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. + If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. @@ -662,9 +662,9 @@ Values added without validation might be observed when enumerating the collectio > [!CAUTION] > This method must never be used with untrusted values, unless they were otherwise sufficiently validated. -> +> > What constitutes "sufficient" validation can vary by use case. At a minimum, prohibit newline characters for protocol correctness, for example, `if (value.ContainsAny('\r', '\n', '\0')) throw ...`. This validation should ensure that the server application sees values in the same way as the client application, with the server now being responsible for properly sanitizing its own inputs. -> +> > To guard against attacks such as request smuggling, callers are highly encouraged to validate that these values don't contain newline characters. ]]> @@ -734,9 +734,9 @@ Values added without validation might be observed when enumerating the collectio > [!CAUTION] > This method must never be used with untrusted values, unless they were otherwise sufficiently validated. -> +> > What constitutes "sufficient" validation can vary by use case. At a minimum, prohibit newline characters for protocol correctness, for example, `if (value.ContainsAny('\r', '\n', '\0')) throw ...`. This validation should ensure that the server application sees values in the same way as the client application, with the server now being responsible for properly sanitizing its own inputs. -> +> > To guard against attacks such as request smuggling, callers are highly encouraged to validate that these values don't contain newline characters. ]]> diff --git a/xml/System.Net.Http.Headers/MediaTypeHeaderValue.xml b/xml/System.Net.Http.Headers/MediaTypeHeaderValue.xml index a4555f04d69..b41b75f4011 100644 --- a/xml/System.Net.Http.Headers/MediaTypeHeaderValue.xml +++ b/xml/System.Net.Http.Headers/MediaTypeHeaderValue.xml @@ -57,13 +57,13 @@ Represents a media type used in a Content-Type header as defined in the RFC 2616. - class provides support for the media type used in a Content-Type header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - - An example of a media-type would be "text/plain; charset=iso-8859-5". - + class provides support for the media type used in a Content-Type header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + + An example of a media-type would be "text/plain; charset=iso-8859-5". + ]]> @@ -320,13 +320,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -368,11 +368,11 @@ Gets or sets the media-type header value. The media-type header value. - diff --git a/xml/System.Net.Http.Headers/NameValueHeaderValue.xml b/xml/System.Net.Http.Headers/NameValueHeaderValue.xml index 69bec80269b..5d5fb5eace6 100644 --- a/xml/System.Net.Http.Headers/NameValueHeaderValue.xml +++ b/xml/System.Net.Http.Headers/NameValueHeaderValue.xml @@ -57,11 +57,11 @@ Represents a name/value pair used in various headers as defined in RFC 2616. - class provides support for name/value pairs used in various headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - + class provides support for name/value pairs used in various headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + ]]> @@ -294,13 +294,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/NameValueWithParametersHeaderValue.xml b/xml/System.Net.Http.Headers/NameValueWithParametersHeaderValue.xml index b3a2635ace1..5ac93c16a50 100644 --- a/xml/System.Net.Http.Headers/NameValueWithParametersHeaderValue.xml +++ b/xml/System.Net.Http.Headers/NameValueWithParametersHeaderValue.xml @@ -57,11 +57,11 @@ Represents a name/value pair with parameters used in various headers as defined in RFC 2616. - class provides support for a name/value pair with parameters used in various headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - + class provides support for a name/value pair with parameters used in various headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + ]]> @@ -290,13 +290,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/ProductHeaderValue.xml b/xml/System.Net.Http.Headers/ProductHeaderValue.xml index 494602fc6e8..865c0d8aca2 100644 --- a/xml/System.Net.Http.Headers/ProductHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ProductHeaderValue.xml @@ -57,11 +57,11 @@ Represents a product token value in a User-Agent header. - class provides support for the product token header value used in a User-Agent header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - + class provides support for the product token header value used in a User-Agent header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + ]]> @@ -252,13 +252,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/ProductInfoHeaderValue.xml b/xml/System.Net.Http.Headers/ProductInfoHeaderValue.xml index 6d50e141137..a3f6ac813bb 100644 --- a/xml/System.Net.Http.Headers/ProductInfoHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ProductInfoHeaderValue.xml @@ -342,7 +342,7 @@ ## Remarks A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. - The method is suitable for use in hashing algorithms and data structures such as a hash table. + The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> diff --git a/xml/System.Net.Http.Headers/RangeConditionHeaderValue.xml b/xml/System.Net.Http.Headers/RangeConditionHeaderValue.xml index ad5eabdb30e..4a40296867e 100644 --- a/xml/System.Net.Http.Headers/RangeConditionHeaderValue.xml +++ b/xml/System.Net.Http.Headers/RangeConditionHeaderValue.xml @@ -368,7 +368,7 @@ ## Remarks A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. - The method is suitable for use in hashing algorithms and data structures such as a hash table. + The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> diff --git a/xml/System.Net.Http.Headers/RangeHeaderValue.xml b/xml/System.Net.Http.Headers/RangeHeaderValue.xml index 465391ab159..203bc315d5f 100644 --- a/xml/System.Net.Http.Headers/RangeHeaderValue.xml +++ b/xml/System.Net.Http.Headers/RangeHeaderValue.xml @@ -57,27 +57,27 @@ Represents a Range header value. - class provides support for the Range header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - - Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. - - The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. - - An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - + class provides support for the Range header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + + Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. + + The Range header on a request allows a client to request that it only wants to receive some part of the specified range of bytes in an HTTP entity. Servers are not required to support Range header requests. + + An example of a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: + + `Range: bytes=0-99\r\n\r\n` + + A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: + + `Accept-Ranges: bytes\r\n\r\n` + + If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: + + `Accept-Ranges: none\r\n\r\n` + ]]> @@ -166,24 +166,24 @@ The position at which to stop sending data. Initializes a new instance of the class with a byte range. - class with a Range header containing a specified byte range. - - An example of a Range header with a byte range in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - For this example, the `from` parameter would be specified as 0 and the `to` parameter would be specified as 99. - + class with a Range header containing a specified byte range. + + An example of a Range header with a byte range in an HTTP protocol request that requests the first 100 bytes would be would be the following: + + `Range: bytes=0-99\r\n\r\n` + + For this example, the `from` parameter would be specified as 0 and the `to` parameter would be specified as 99. + ]]> - is greater than - - -or- - + is greater than + + -or- + or is less than 0. @@ -275,13 +275,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/RangeItemHeaderValue.xml b/xml/System.Net.Http.Headers/RangeItemHeaderValue.xml index 5fb80784c31..9ec909a2042 100644 --- a/xml/System.Net.Http.Headers/RangeItemHeaderValue.xml +++ b/xml/System.Net.Http.Headers/RangeItemHeaderValue.xml @@ -51,25 +51,25 @@ Represents a byte range in a Range header value. - class provides support for a byte range in a Range header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - - A Range header can specify multiple byte ranges. - - An example of a byte-range in a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: - - `Range: bytes=0-99\r\n\r\n` - - A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: - - `Accept-Ranges: bytes\r\n\r\n` - - If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: - - `Accept-Ranges: none\r\n\r\n` - + class provides support for a byte range in a Range header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + + A Range header can specify multiple byte ranges. + + An example of a byte-range in a Range header in an HTTP protocol request that requests the first 100 bytes would be would be the following: + + `Range: bytes=0-99\r\n\r\n` + + A HTTP server indicates support for Range headers with the Accept-Ranges header. An example of the Accept-Ranges header from a server that supports byte-ranges would be as follows: + + `Accept-Ranges: bytes\r\n\r\n` + + If an Accept-Ranges header is not received in the header of the response from the server, then the server does not support Range headers. An example of the Accept-Ranges header from a server that does not support ranges, but recognizes the Accept-Ranges header, would be as follows: + + `Accept-Ranges: none\r\n\r\n` + ]]> @@ -112,22 +112,22 @@ The position at which to stop sending data. Initializes a new instance of the class. - - is greater than - - -or- - + is greater than + + -or- + or is less than 0. @@ -257,13 +257,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/RetryConditionHeaderValue.xml b/xml/System.Net.Http.Headers/RetryConditionHeaderValue.xml index 2b8e4c17456..f986eda03ec 100644 --- a/xml/System.Net.Http.Headers/RetryConditionHeaderValue.xml +++ b/xml/System.Net.Http.Headers/RetryConditionHeaderValue.xml @@ -317,7 +317,7 @@ ## Remarks A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. - The method is suitable for use in hashing algorithms and data structures such as a hash table. + The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> diff --git a/xml/System.Net.Http.Headers/StringWithQualityHeaderValue.xml b/xml/System.Net.Http.Headers/StringWithQualityHeaderValue.xml index 6261d1bd8e2..f90ddbc09a1 100644 --- a/xml/System.Net.Http.Headers/StringWithQualityHeaderValue.xml +++ b/xml/System.Net.Http.Headers/StringWithQualityHeaderValue.xml @@ -57,13 +57,13 @@ Represents a string header value with an optional quality. - class provides support for strings with a quality factor used in some headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - - Quality factors allow the user agent to indicate the relative degree of preference for various options in various headers including the Accept, Accept-Charset, Accept-Encoding, and Accept-Language headers. Quality uses a scale from 0 to 1. The default value is q=1. - + class provides support for strings with a quality factor used in some headers as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + + Quality factors allow the user agent to indicate the relative degree of preference for various options in various headers including the Accept, Accept-Charset, Accept-Encoding, and Accept-Language headers. Quality uses a scale from 0 to 1. The default value is q=1. + ]]> @@ -246,13 +246,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/TransferCodingHeaderValue.xml b/xml/System.Net.Http.Headers/TransferCodingHeaderValue.xml index 995e38c9532..7aceb16beef 100644 --- a/xml/System.Net.Http.Headers/TransferCodingHeaderValue.xml +++ b/xml/System.Net.Http.Headers/TransferCodingHeaderValue.xml @@ -57,11 +57,11 @@ Represents an accept-encoding header value. - class provides support for the Accept-Encoding header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. - + class provides support for the Accept-Encoding header as defined in [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=241642) by the IETF. + ]]> @@ -242,13 +242,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http.Headers/ViaHeaderValue.xml b/xml/System.Net.Http.Headers/ViaHeaderValue.xml index cdd948ceb77..54d33f3c77d 100644 --- a/xml/System.Net.Http.Headers/ViaHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ViaHeaderValue.xml @@ -353,13 +353,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -530,11 +530,11 @@ Gets the host and port that the request or response was received by. The host and port that the request or response was received by. - diff --git a/xml/System.Net.Http.Headers/WarningHeaderValue.xml b/xml/System.Net.Http.Headers/WarningHeaderValue.xml index b91574c8fdc..16f529598a2 100644 --- a/xml/System.Net.Http.Headers/WarningHeaderValue.xml +++ b/xml/System.Net.Http.Headers/WarningHeaderValue.xml @@ -359,13 +359,13 @@ Serves as a hash function for an object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> diff --git a/xml/System.Net.Http/ByteArrayContent.xml b/xml/System.Net.Http/ByteArrayContent.xml index 6cb94f695cb..704374f0d3b 100644 --- a/xml/System.Net.Http/ByteArrayContent.xml +++ b/xml/System.Net.Http/ByteArrayContent.xml @@ -98,11 +98,11 @@ The content used to initialize the . Initializes a new instance of the class. - class does not internally copy the provided byte array but keeps a reference to it instead. Callers should not modify the data in the array until after the content is sent. - + class does not internally copy the provided byte array but keeps a reference to it instead. Callers should not modify the data in the array until after the content is sent. + ]]> The parameter is . @@ -148,28 +148,28 @@ The class does not internally copy the p The number of bytes in the starting from the parameter used to initialize the . Initializes a new instance of the class. - class does not internally copy the provided byte array but keeps a reference to it instead. Callers should not modify the data in the array until after the content is sent. - + class does not internally copy the provided byte array but keeps a reference to it instead. Callers should not modify the data in the array until after the content is sent. + Only the range specified by the `offset` parameter and the `count` parameter is used as content. - + ]]> The parameter is . - The parameter is less than zero. - - -or- - - The parameter is greater than the length of content specified by the parameter. - - -or- - - The parameter is less than zero. - - -or- - + The parameter is less than zero. + + -or- + + The parameter is greater than the length of content specified by the parameter. + + -or- + + The parameter is less than zero. + + -or- + The parameter is greater than the length of content specified by the parameter - minus the parameter. @@ -245,11 +245,11 @@ The class does not internally copy the p Creates an HTTP content stream as an asynchronous operation for reading whose backing store is memory from the . The task object representing the asynchronous operation. - object will complete after all of the content stream has been created. - + object will complete after all of the content stream has been created. + ]]> @@ -349,11 +349,11 @@ The class does not internally copy the p Serialize and write the byte array provided in the constructor to an HTTP content stream as an asynchronous operation. The task object representing the asynchronous operation. - object completes, the whole byte array has been written to the `stream` parameter. - + object completes, the whole byte array has been written to the `stream` parameter. + ]]> @@ -401,11 +401,11 @@ The class does not internally copy the p Serialize and write the byte array provided in the constructor to an HTTP content stream as an asynchronous operation. The task object representing the asynchronous operation. - object completes, the whole byte array has been written to the `stream` parameter. - + object completes, the whole byte array has been written to the `stream` parameter. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -452,13 +452,13 @@ The class does not internally copy the p if is a valid length; otherwise, . - method gives a derived content type the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. - - This method always returned `true` for . - + method gives a derived content type the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. + + This method always returned `true` for . + ]]> diff --git a/xml/System.Net.Http/DelegatingHandler.xml b/xml/System.Net.Http/DelegatingHandler.xml index 7cdbac16221..a964eca26fb 100644 --- a/xml/System.Net.Http/DelegatingHandler.xml +++ b/xml/System.Net.Http/DelegatingHandler.xml @@ -51,7 +51,7 @@ property before calling ; otherwise, an will be thrown. + An application should provide an inner handler either in the constructor or through the property before calling ; otherwise, an will be thrown. Note that property may be a delegating handler as well. This approach allows the creation of handler stacks to process the HTTP response messages. @@ -106,7 +106,7 @@ . + The inner handle can be set using the . ]]> @@ -238,7 +238,7 @@ property can only be set before the class is used (the method is called). + This property can only be set before the class is used (the method is called). Note that property may be a delegating handler too, although this is uncommon. This approach allows the creation of handler stacks for the HTTP response messages. @@ -284,7 +284,7 @@ ## Remarks - The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. + The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. ]]> @@ -336,9 +336,9 @@ method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. + This operation does not block. This overridable implementation of method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. - The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. + The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. ]]> diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 6d74bd2e88b..fbc6bc7ad84 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -476,9 +476,9 @@ The URL may optionally include a username and password for proxy authentication, ## Remarks `DefaultRequestVersion` is by default. -The `DefaultRequestVersion` property specifies the default HTTP version to use for requests sent using this instance when it constructs the to send, specifically with calls to methods such as , , , , , , , and . +The `DefaultRequestVersion` property specifies the default HTTP version to use for requests sent using this instance when it constructs the to send, specifically with calls to methods such as , , , , , , , and . -The `DefaultRequestVersion` property doesn't apply to the method. The parameter passed as the argument to the method has its own `Version` property that controls the HTTP version used for the request. +The `DefaultRequestVersion` property doesn't apply to the method. The parameter passed as the argument to the method has its own `Version` property that controls the HTTP version used for the request. The `DefaultRequestVersion` property can be changed as long as the instance has not started any request. ]]> @@ -519,7 +519,7 @@ The `DefaultRequestVersion` property can be changed as long as the or overloads that accept an . +This property has no effect on any of the or overloads that accept an . ]]> The instance has already started one or more requests. @@ -593,7 +593,7 @@ This property has no effect on any of the object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations: @@ -671,7 +671,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations: @@ -755,7 +755,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -839,7 +839,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -917,7 +917,7 @@ The is not an absolute URI. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. - When this method is called, the method is called to abort all pending requests. + When this method is called, the method is called to abort all pending requests. ]]> @@ -997,7 +997,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1067,7 +1067,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1142,7 +1142,7 @@ The is not an absolute URI. object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + This operation doesn't block. The returned object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1214,7 +1214,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1290,7 +1290,7 @@ The is not an absolute URI. object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + This operation doesn't block. The returned object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1361,7 +1361,7 @@ The is not an absolute URI. object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1442,7 +1442,7 @@ The is not an absolute URI. object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + This operation doesn't block. The returned object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1520,7 +1520,7 @@ The is not an absolute URI. object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. + This operation doesn't block. The returned object will complete based on the `completionOption` parameter after the part or all of the response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -1616,8 +1616,8 @@ The is not an absolute URI. object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -1692,8 +1692,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -1765,8 +1765,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -1834,8 +1834,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -1933,8 +1933,8 @@ The response status code was outside of the range of 200-299 (which indicate suc ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read or buffer the response body. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned [Task\](xref:System.Threading.Tasks.Task`1) object will complete after the response headers are read. This method does not read or buffer the response body. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2009,8 +2009,8 @@ The response status code was outside of the range of 200-299 (which indicate suc ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned [Task\](xref:System.Threading.Tasks.Task`1) object will complete after the response headers are read. This method does not read nor buffer the response body. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2081,8 +2081,8 @@ The response status code was outside of the range of 200-299 (which indicate suc ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned [Task\](xref:System.Threading.Tasks.Task`1) object will complete after the response headers are read. This method does not read nor buffer the response body. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2150,8 +2150,8 @@ The response status code was outside of the range of 200-299 (which indicate suc ](xref:System.Threading.Tasks.Task%601) object will complete after the response headers are read. This method does not read nor buffer the response body. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned [Task\](xref:System.Threading.Tasks.Task`1) object will complete after the response headers are read. This method does not read nor buffer the response body. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2248,8 +2248,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2324,8 +2324,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2396,8 +2396,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2465,8 +2465,8 @@ The response status code was outside of the range of 200-299 (which indicate suc object will complete after the whole response body is read. - Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. + This operation doesn't block. The returned object will complete after the whole response body is read. + Internally, this operation uses to ensure the response status code is in the success range (200-299) and throws an if it is not. In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. > [!NOTE] @@ -2595,7 +2595,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. ]]> @@ -2653,7 +2653,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. ]]> @@ -2719,7 +2719,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. ]]> @@ -2779,7 +2779,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. ]]> @@ -2861,7 +2861,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -2927,7 +2927,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3001,7 +3001,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3073,7 +3073,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3168,7 +3168,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3234,7 +3234,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3308,7 +3308,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3380,7 +3380,7 @@ The size specified is greater than the maximum allowed buffer size. object will complete after the whole response (including content) is read. + This operation doesn't block. The returned object will complete after the whole response (including content) is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3742,7 +3742,7 @@ The custom does not override object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3809,7 +3809,7 @@ This method stores in the task it returns all non-usage exceptions that the meth object will complete as soon as a response is available or the entire response including content is read. + This operation doesn't block. Depending on the value of the `completionOption` parameter, the returned object will complete as soon as a response is available or the entire response including content is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3876,7 +3876,7 @@ This method stores in the task it returns all non-usage exceptions that the meth object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. + This operation doesn't block. The returned object will complete once the entire response including content is read. The behavior is the same as if has been explicitly specified. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -3949,7 +3949,7 @@ This method stores in the task it returns all non-usage exceptions that the meth object will complete as soon as a response is available or the entire response including content is read. + This operation doesn't block. Depending on the value of the `completionOption` parameter, the returned object will complete as soon as a response is available or the entire response including content is read. > [!NOTE] > In case of timeout, different exceptions are thrown on different .NET implementations. @@ -4018,7 +4018,7 @@ This method stores in the task it returns all non-usage exceptions that the meth To set an infinite timeout, set the property value to . - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. The same timeout will apply for all requests using this instance. You may also set different timeouts for individual requests using a on a task. Note that only the shorter of the two timeouts will apply. diff --git a/xml/System.Net.Http/HttpClientHandler.xml b/xml/System.Net.Http/HttpClientHandler.xml index 28234e3ab41..ddb75632bd7 100644 --- a/xml/System.Net.Http/HttpClientHandler.xml +++ b/xml/System.Net.Http/HttpClientHandler.xml @@ -133,9 +133,9 @@ to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. - If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. + If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. The Authorization header is cleared on auto-redirects and the handler automatically tries to re-authenticate to the redirected location. No other headers are cleared. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. @@ -405,7 +405,7 @@ On .NET Core, the key usage attribute on the X509 certificate, if present, is re ## Remarks The property provides an instance of the class that contains the cookies associated with this handler. - If the property is `true`, the property represents the cookie container used to store the server cookies. The user can set custom cookies before sending requests using this property. If the property is false and the user adds cookies to , cookies are ignored and not sent to the server. Setting the to `null` will throw an exception. + If the property is `true`, the property represents the cookie container used to store the server cookies. The user can set custom cookies before sending requests using this property. If the property is false and the user adds cookies to , cookies are ignored and not sent to the server. Setting the to `null` will throw an exception. ]]> @@ -517,7 +517,7 @@ If the property h handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; ``` - This gives implementations a known object reference identity that expresses the developer's intention. If the object stored in the property is reference equals to , the runtime is able to entirely disable validation on a platform that would otherwise throw a . + This gives implementations a known object reference identity that expresses the developer's intention. If the object stored in the property is reference equals to , the runtime is able to entirely disable validation on a platform that would otherwise throw a . As a side benefit, developers can use this property to make it easier for tools to flag the danger of disabling certificate validation, which makes it easier for developers to avoid shipping insecure applications. @@ -1020,7 +1020,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. + The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the handler will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the handler uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. @@ -1028,7 +1028,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA - The destination contains a flat name (no dots in the URL). - The destination contains a loopback address ( or ) or the destination contains an assigned to the local computer. -- The domain suffix of the destination matches the local computer's domain suffix (). +- The domain suffix of the destination matches the local computer's domain suffix (). ]]> @@ -1151,7 +1151,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA to represent the asynchronous operation. When the operation completes, contains the response message. + This operation is does not block. It returns an instance of to represent the asynchronous operation. When the operation completes, contains the response message. ]]> @@ -1213,7 +1213,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA can be used to obtain and validate the server certificate. + The can be used to obtain and validate the server certificate. ## Examples The following code example displays the server certificate. diff --git a/xml/System.Net.Http/HttpContent.xml b/xml/System.Net.Http/HttpContent.xml index 6e7496ee982..629293504b6 100644 --- a/xml/System.Net.Http/HttpContent.xml +++ b/xml/System.Net.Http/HttpContent.xml @@ -482,11 +482,11 @@ Once the operation completes, the returned memory stream represents the HTTP con object will complete after all of the content has been written to the memory stream. + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. - The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string. + The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string. ]]> @@ -527,11 +527,11 @@ Once the operation completes, the returned memory stream represents the HTTP con object will complete after all of the content has been written to the memory stream. + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. - The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string.) + The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string.) ]]> @@ -741,7 +741,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks This operation will not block. The returned object will complete after all of the content has been serialized to the memory buffer. - After content is serialized to a memory buffer, calls to one of the methods will copy the content of the memory buffer to the target stream. + After content is serialized to a memory buffer, calls to one of the methods will copy the content of the memory buffer to the target stream. ]]> @@ -792,7 +792,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks This operation will not block. The returned object will complete after all of the content has been serialized to the memory buffer. - After content is serialized to a memory buffer, calls to one of the methods will copy the content of the memory buffer to the target stream. + After content is serialized to a memory buffer, calls to one of the methods will copy the content of the memory buffer to the target stream. If the content exceeds the value passed in the `maxBufferSize` parameter, an exception is thrown. @@ -912,9 +912,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the content has been written as a byte array. + This operation will not block. The returned object will complete after all of the content has been written as a byte array. - Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. + Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. Note that this method will internally buffer the content via . @@ -957,9 +957,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the content has been written as a byte array. + This operation will not block. The returned object will complete after all of the content has been written as a byte array. - Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. + Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. Note that this method will internally buffer the content via . @@ -983,7 +983,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks Note that this method will internally buffer the content unless has been implemented to do otherwise. - For example, when using , a method such as returns a class derived from that conditionally buffers based on what's passed for the `completionOption` parameter. + For example, when using , a method such as returns a class derived from that conditionally buffers based on what's passed for the `completionOption` parameter. ]]> @@ -1115,9 +1115,9 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the stream that represents content has been read. + This operation will not block. The returned object will complete after all of the stream that represents content has been read. - Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1160,10 +1160,10 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the stream that represents content has been read (unless has been implemented to do otherwise). -For example, when using , a method such as returns a class derived from that conditionally buffers based on what's passed for the `completionOption` parameter. + This operation will not block. The returned object will complete after all of the stream that represents content has been read (unless has been implemented to do otherwise). +For example, when using , a method such as returns a class derived from that conditionally buffers based on what's passed for the `completionOption` parameter. - Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1212,9 +1212,9 @@ For example, when using , a method such as object will complete after all of the content has been written as a string. + This operation will not block. The returned object will complete after all of the content has been written as a string. - Once the operation completes, the property on the returned task object contains the string with the HTTP content. + Once the operation completes, the property on the returned task object contains the string with the HTTP content. Note that this method will internally buffer the content via . @@ -1257,9 +1257,9 @@ For example, when using , a method such as object will complete after all of the content has been written as a string. + This operation will not block. The returned object will complete after all of the content has been written as a string. - Once the operation completes, the property on the returned task object contains the string with the HTTP content. + Once the operation completes, the property on the returned task object contains the string with the HTTP content. Note that this method will internally buffer the content via . @@ -1367,7 +1367,7 @@ For example, when using , a method such as object will complete after all of the content has been serialized to the stream object passed in the `stream` parameter. + This operation will not block. The returned object will complete after all of the content has been serialized to the stream object passed in the `stream` parameter. ]]> @@ -1419,7 +1419,7 @@ For example, when using , a method such as object will complete after all of the content has been serialized to the stream object passed in the `stream` parameter. + This operation will not block. The returned object will complete after all of the content has been serialized to the stream object passed in the `stream` parameter. ]]> @@ -1470,7 +1470,7 @@ For example, when using , a method such as method gives a HTTP content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. + The method gives a HTTP content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. ]]> diff --git a/xml/System.Net.Http/HttpMessageHandler.xml b/xml/System.Net.Http/HttpMessageHandler.xml index 58ab6f0e718..cbbea303c77 100644 --- a/xml/System.Net.Http/HttpMessageHandler.xml +++ b/xml/System.Net.Http/HttpMessageHandler.xml @@ -46,23 +46,23 @@ A base type for HTTP message handlers. - - A class used to plug a handler into a handler chain. - -2. - A simple class to derive from that supports the most common requirements for most applications. - -3. - A class that operates at the bottom of the handler chain that actually handles the HTTP transport operations. - -4. - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the object. - - If developers derive classes from and override the method, they must make sure that can get called concurrently by different threads. - - This is necessary since methods on can be called concurrently and need a guarantee of thread safety. So if a handler is assigned to an instance, the method of the handler may get called concurrently by the instance and needs to be thread safe. - + - A class used to plug a handler into a handler chain. + +2. - A simple class to derive from that supports the most common requirements for most applications. + +3. - A class that operates at the bottom of the handler chain that actually handles the HTTP transport operations. + +4. - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the object. + + If developers derive classes from and override the method, they must make sure that can get called concurrently by different threads. + + This is necessary since methods on can be called concurrently and need a guarantee of thread safety. So if a handler is assigned to an instance, the method of the handler may get called concurrently by the instance and needs to be thread safe. + ]]> @@ -194,13 +194,13 @@ to release both managed and unmanaged resources; to releases only unmanaged resources. Releases the unmanaged resources used by the and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. -When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. - +When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. + ]]> @@ -285,13 +285,13 @@ When the `disposing` parameter is `true`, this method releases all resources hel Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete once the entire response including content is read. - - The method is used primarily by the system. This method is called by the system when one of the methods is called. Most apps will never call this method. - + object will complete once the entire response including content is read. + + The method is used primarily by the system. This method is called by the system when one of the methods is called. Most apps will never call this method. + ]]> The was . diff --git a/xml/System.Net.Http/HttpMessageInvoker.xml b/xml/System.Net.Http/HttpMessageInvoker.xml index 097336f51ca..cdf5b644fe4 100644 --- a/xml/System.Net.Http/HttpMessageInvoker.xml +++ b/xml/System.Net.Http/HttpMessageInvoker.xml @@ -52,13 +52,13 @@ A specialty class that allows applications to call the method on an HTTP handler chain. - and other message originators. - - Most applications that are connecting to a web site will use one of the methods on the class. - + and other message originators. + + Most applications that are connecting to a web site will use one of the methods on the class. + ]]> @@ -356,13 +356,13 @@ Send an HTTP request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete once the entire response including content is read. - - Most applications that are connecting to a web site will use one of the methods on the class. - + object will complete once the entire response including content is read. + + Most applications that are connecting to a web site will use one of the methods on the class. + ]]> The was . diff --git a/xml/System.Net.Http/HttpMethod.xml b/xml/System.Net.Http/HttpMethod.xml index 4d2d671f10d..9f0ab612b4c 100644 --- a/xml/System.Net.Http/HttpMethod.xml +++ b/xml/System.Net.Http/HttpMethod.xml @@ -55,7 +55,7 @@ is to use one of the static properties on this class. However, if an app needs a different value for the HTTP method, the constructor initializes a new instance of the with an HTTP method that the app specifies. + The most common usage of is to use one of the static properties on this class. However, if an app needs a different value for the HTTP method, the constructor initializes a new instance of the with an HTTP method that the app specifies. ]]> @@ -100,7 +100,7 @@ constructor initializes a new instance of the with an HTTP method that the app specifies. + If an app needs a different value for the HTTP method from one of the static properties, the constructor initializes a new instance of the with an HTTP method that the app specifies. ]]> @@ -367,7 +367,7 @@ method is suitable for use in hashing algorithms and data structures such as a hash table. + A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection. The method is suitable for use in hashing algorithms and data structures such as a hash table. ]]> diff --git a/xml/System.Net.Http/HttpRequestMessage.xml b/xml/System.Net.Http/HttpRequestMessage.xml index a5f3fc3b5cf..bf776c2436e 100644 --- a/xml/System.Net.Http/HttpRequestMessage.xml +++ b/xml/System.Net.Http/HttpRequestMessage.xml @@ -590,8 +590,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel is a relative Uri, it will be combined with the . + If the request is a relative URI, it will be combined with the . ]]> diff --git a/xml/System.Net.Http/HttpRequestOptions.xml b/xml/System.Net.Http/HttpRequestOptions.xml index d97dc956769..c417e31546b 100644 --- a/xml/System.Net.Http/HttpRequestOptions.xml +++ b/xml/System.Net.Http/HttpRequestOptions.xml @@ -171,12 +171,12 @@ The object to add to the . Adds an item to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -209,12 +209,12 @@ This member is an explicit interface member implementation. It can be used only Removes all items from the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -252,12 +252,12 @@ This member is an explicit interface member implementation. It can be used only if is found in the ; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -295,12 +295,12 @@ This member is an explicit interface member implementation. It can be used only The zero-based index in at which copying begins. Copies the elements of the to an , starting at a particular index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -333,12 +333,12 @@ This member is an explicit interface member implementation. It can be used only Gets the number of elements contained in the . The number of elements contained in the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -372,12 +372,12 @@ This member is an explicit interface member implementation. It can be used only if the is read-only; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -415,12 +415,12 @@ This member is an explicit interface member implementation. It can be used only if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -458,12 +458,12 @@ This member is an explicit interface member implementation. It can be used only The object to use as the value of the element to add. Adds an element with the provided key and value to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -501,12 +501,12 @@ This member is an explicit interface member implementation. It can be used only if the contains an element with the key; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -549,12 +549,12 @@ This member is an explicit interface member implementation. It can be used only Gets or sets the element with the specified key. The element with the specified key. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -587,12 +587,12 @@ This member is an explicit interface member implementation. It can be used only Gets an containing the keys of the . An containing the keys of the object that implements . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -630,12 +630,12 @@ This member is an explicit interface member implementation. It can be used only if the element is successfully removed; otherwise, . This method also returns if was not found in the original . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -672,12 +672,12 @@ This member is an explicit interface member implementation. It can be used only if the contains an element with the specified key; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -716,12 +716,12 @@ This member is an explicit interface member implementation. It can be used only Gets an containing the values in the . An containing the values in the object that implements . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -755,12 +755,12 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -981,12 +981,12 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator that iterates through a collection. An object that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml index 42116ca1372..64e468d3935 100644 --- a/xml/System.Net.Http/HttpResponseMessage.xml +++ b/xml/System.Net.Http/HttpResponseMessage.xml @@ -55,7 +55,7 @@ is from one of the methods. + A common way to get an is from one of the methods. ## Examples @@ -83,7 +83,7 @@ is from one of the methods. + A common way to get an is from one of the methods. ]]> @@ -359,9 +359,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel method throws an if is outside of the range 200-299 (the range of status codes indicating success according to the standard). + The method throws an if is outside of the range 200-299 (the range of status codes indicating success according to the standard). + In some scenarios, you might need more control over which status codes are considered to be successful; for example, an API might be expected to always return `200 OK`. In such cases, we recommend to manually check if matches the expected value. - In .NET Framework, if the is not `null`, this method also calls to free managed and unmanaged resources. Starting with .NET Core 3.0, the content is not disposed. + + In .NET Framework, if the is not `null`, this method also calls to free managed and unmanaged resources. Starting with .NET Core 3.0, the content is not disposed. ]]> diff --git a/xml/System.Net.Http/MessageProcessingHandler.xml b/xml/System.Net.Http/MessageProcessingHandler.xml index 07e8a78c794..5c74dd2a545 100644 --- a/xml/System.Net.Http/MessageProcessingHandler.xml +++ b/xml/System.Net.Http/MessageProcessingHandler.xml @@ -48,13 +48,13 @@ A base type for handlers which only do some small processing of request and/or response messages. - is useful if the handler doesn't require asynchronous operations, because operations on request and response messages are fast. - - The most common usage is to derive from this class and override the and methods. - + is useful if the handler doesn't require asynchronous operations, because operations on request and response messages are fast. + + The most common usage is to derive from this class and override the and methods. + ]]> @@ -185,11 +185,11 @@ Performs processing on each request sent to the server. The HTTP request message that was processed. - The cancellation token was canceled. This exception is stored into the returned task. @@ -237,11 +237,11 @@ Perform processing on each response from the server. The HTTP response message that was processed. - The cancellation token was canceled. This exception is stored into the returned task. @@ -326,11 +326,11 @@ Sends an HTTP request to the inner handler to send to the server as an asynchronous operation. The task object representing the asynchronous operation. - method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. - + method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. + ]]> The was . diff --git a/xml/System.Net.Http/MultipartContent.xml b/xml/System.Net.Http/MultipartContent.xml index 401dd51861d..7a797875d6b 100644 --- a/xml/System.Net.Http/MultipartContent.xml +++ b/xml/System.Net.Http/MultipartContent.xml @@ -270,7 +270,7 @@ If your server doesn't support such contents with zero parts, consider condition to use a custom stream that contains an array, with each HTTP content entity and its boundary encoded and serialized to a instance. +This method overrides to use a custom stream that contains an array, with each HTTP content entity and its boundary encoded and serialized to a instance. ]]> @@ -312,11 +312,11 @@ This method overrides to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. + This method overrides to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. - This operation will not block. The returned object will complete after all of the content has been written to the memory stream. + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. ]]> @@ -357,11 +357,11 @@ This method overrides to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. + This method overrides to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. - This operation will not block. The returned object will complete after all of the content has been written to the memory stream. + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. ]]> @@ -606,7 +606,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the content has been serialized to the target stream. + This operation will not block. The returned object will complete after all of the content has been serialized to the target stream. ]]> @@ -658,7 +658,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel object will complete after all of the content has been serialized to the target stream. + This operation will not block. The returned object will complete after all of the content has been serialized to the target stream. ]]> @@ -759,7 +759,7 @@ This member is an explicit interface member implementation. It can be used only method gives HTTP multipart content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. + The method gives HTTP multipart content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. ]]> diff --git a/xml/System.Net.Http/SocketsHttpHandler.xml b/xml/System.Net.Http/SocketsHttpHandler.xml index c40b0a5f03d..0b08b1a988a 100644 --- a/xml/System.Net.Http/SocketsHttpHandler.xml +++ b/xml/System.Net.Http/SocketsHttpHandler.xml @@ -138,16 +138,16 @@ The `SocketsHttpHandler` class provides the implementation used by higher-level to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. - If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. + If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. The Authorization header is cleared on auto-redirects and the handler automatically tries to re-authenticate to the redirected location. No other headers are cleared. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. If you are using cookies by specifically adding them to the collection, these are not cleared when a redirect is followed, as the handler has no way of knowing what domain a cookie is allowed for. If you want to mimic browser behavior, use the class which allows you to specify the target domain for a cookie. > [!NOTE] -> The handler never follows a redirection from HTTPS to HTTP even if is set to `true`. +> The handler never follows a redirection from HTTPS to HTTP even if is set to `true`. ]]> @@ -498,7 +498,7 @@ The default proxy is used only when define the timeout for the `100 Continue` server response. + When request contain `Expect: 100-continue` header the server should respond HTTP status `100 Continue` before the client sends the body. define the timeout for the `100 Continue` server response. ]]> diff --git a/xml/System.Net.Http/StreamContent.xml b/xml/System.Net.Http/StreamContent.xml index ce55076d664..c7b9860a4de 100644 --- a/xml/System.Net.Http/StreamContent.xml +++ b/xml/System.Net.Http/StreamContent.xml @@ -98,11 +98,11 @@ The content used to initialize the . Creates a new instance of the class. - object calls on the provided object when is called. +The object calls on the provided object when is called. ]]> @@ -146,11 +146,11 @@ The object calls The size, in bytes, of the buffer for the . Creates a new instance of the class. - object calls on the provided object when is called. - + object calls on the provided object when is called. + ]]> The was . @@ -271,13 +271,13 @@ The object calls to release both managed and unmanaged resources; to releases only unmanaged resources. Releases the unmanaged resources used by the and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `false`. -When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. - +When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose()` method of each referenced object. + ]]> @@ -377,11 +377,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel Serialize the HTTP content to a stream as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after all of the content has been serialized to the target stream. - + object will complete after all of the content has been serialized to the target stream. + ]]> @@ -429,11 +429,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel Serialize the HTTP content to a stream as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after all of the content has been serialized to the target stream. - + object will complete after all of the content has been serialized to the target stream. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -480,11 +480,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel if is a valid length; otherwise, . - method gives HTTP stream content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. - + method gives HTTP stream content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. + ]]> diff --git a/xml/System.Net.Http/WebRequestHandler.xml b/xml/System.Net.Http/WebRequestHandler.xml index 14af5506c45..48ec3e875b4 100644 --- a/xml/System.Net.Http/WebRequestHandler.xml +++ b/xml/System.Net.Http/WebRequestHandler.xml @@ -66,7 +66,7 @@ property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. + An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. ]]> @@ -277,7 +277,7 @@ is `null`, the server certificate will be validated using standard well-known certificate authorities. + If the is `null`, the server certificate will be validated using standard well-known certificate authorities. ]]> diff --git a/xml/System.Net.Http/WinHttpHandler.xml b/xml/System.Net.Http/WinHttpHandler.xml index 02657aba7c4..b31b069c32f 100644 --- a/xml/System.Net.Http/WinHttpHandler.xml +++ b/xml/System.Net.Http/WinHttpHandler.xml @@ -409,7 +409,7 @@ When this property is set to `true`, all HTTP redirect responses from the server is set to `true`. + The default value for this property is 50. This value only applies if is set to `true`. ]]> diff --git a/xml/System.Net.Mail/AlternateView.xml b/xml/System.Net.Mail/AlternateView.xml index c329e9c676c..a9aae5dd229 100644 --- a/xml/System.Net.Mail/AlternateView.xml +++ b/xml/System.Net.Mail/AlternateView.xml @@ -56,7 +56,7 @@ ## Remarks Use the class to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - This class has two properties and that are used to resolve URLs within the content of the email. is a collection of objects. When rendered, URLs within the email's content are first matched against the URLs in the of each object in the collection, and resolved. is used by the mail reader to resolve relative URLs within the body, and also to resolve relative URLs, in the collection. + This class has two properties and that are used to resolve URLs within the content of the email. is a collection of objects. When rendered, URLs within the email's content are first matched against the URLs in the of each object in the collection, and resolved. is used by the mail reader to resolve relative URLs within the body, and also to resolve relative URLs, in the collection. ]]> @@ -74,7 +74,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -128,7 +128,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -184,7 +184,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -253,7 +253,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -321,7 +321,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -389,7 +389,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> @@ -460,7 +460,7 @@ class call also be initialized by calling one of the methods. + A new instance of the class call also be initialized by calling one of the methods. ]]> diff --git a/xml/System.Net.Mail/AlternateViewCollection.xml b/xml/System.Net.Mail/AlternateViewCollection.xml index 504f31078e6..250894e08de 100644 --- a/xml/System.Net.Mail/AlternateViewCollection.xml +++ b/xml/System.Net.Mail/AlternateViewCollection.xml @@ -58,11 +58,11 @@ Represents a collection of objects. - class to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - + class to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. + ]]> @@ -150,11 +150,11 @@ Releases all resources used by the . - on all views in this collection. This method is called by the method. You do not need to call it in your application. - + on all views in this collection. This method is called by the method. You do not need to call it in your application. + ]]> diff --git a/xml/System.Net.Mail/Attachment.xml b/xml/System.Net.Mail/Attachment.xml index 0aae5bfbdb2..394c353a937 100644 --- a/xml/System.Net.Mail/Attachment.xml +++ b/xml/System.Net.Mail/Attachment.xml @@ -54,11 +54,11 @@ class is used with the class. All messages include a , which contains the content of the message. In addition to the body, you might want to send additional files. These are sent as attachments and are represented as instances. To add an attachment to a mail message, add it to the collection. + The class is used with the class. All messages include a , which contains the content of the message. In addition to the body, you might want to send additional files. These are sent as attachments and are represented as instances. To add an attachment to a mail message, add it to the collection. - Attachment content can be a , , or file name. You can specify the content in an attachment by using any of the constructors. + Attachment content can be a , , or file name. You can specify the content in an attachment by using any of the constructors. - The MIME Content-Type header information for the attachment is represented by the property. The Content-Type header specifies the media type and subtype and any associated parameters. Use to get the instance associated with an attachment. + The MIME Content-Type header information for the attachment is represented by the property. The Content-Type header specifies the media type and subtype and any associated parameters. Use to get the instance associated with an attachment. The MIME Content-Disposition header is represented by the property. The Content-Disposition header specifies the presentation and file time stamps for an attachment. A Content-Disposition header is sent only if the attachment is a file. Use the property to get the instance associated with an attachment. @@ -131,8 +131,8 @@ |Property|Value| |--------------|-----------| -||.| -||.| +||.| +||.| @@ -455,7 +455,7 @@ ## Remarks If `mediaType` is not `null` or equal to (""), it is used to construct the class associated with this attachment. - If `mediaType` and `name` both contain information, the value specified in `name` is used. The property is set to . + If `mediaType` and `name` both contain information, the value specified in `name` is used. The property is set to . If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. @@ -763,7 +763,7 @@ property is used in the Content-Type header generated for this attachment. The is displayed as the attachment's name when the email with the attachment is received. A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1. RFC 2046 provides detailed information about MIME media types and their parameters. These RFCs are available at [https://www.ietf.org/](https://www.ietf.org/). + The property is used in the Content-Type header generated for this attachment. The is displayed as the attachment's name when the email with the attachment is received. A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1. RFC 2046 provides detailed information about MIME media types and their parameters. These RFCs are available at [https://www.ietf.org/](https://www.ietf.org/). diff --git a/xml/System.Net.Mail/AttachmentBase.xml b/xml/System.Net.Mail/AttachmentBase.xml index 02d33cccae6..e4b7c3b57db 100644 --- a/xml/System.Net.Mail/AttachmentBase.xml +++ b/xml/System.Net.Mail/AttachmentBase.xml @@ -558,9 +558,9 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - **Note** Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. + **Note** Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Net.Mail/AttachmentCollection.xml b/xml/System.Net.Mail/AttachmentCollection.xml index d06900bb525..e8e4f5a6b34 100644 --- a/xml/System.Net.Mail/AttachmentCollection.xml +++ b/xml/System.Net.Mail/AttachmentCollection.xml @@ -61,7 +61,7 @@ class are returned by the and properties. + Instances of the class are returned by the and properties. Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. @@ -165,7 +165,7 @@ method. You do not have to call it in your application. + This method is called by the method. You do not have to call it in your application. ]]> diff --git a/xml/System.Net.Mail/LinkedResourceCollection.xml b/xml/System.Net.Mail/LinkedResourceCollection.xml index 3eb5c4133ec..7dc902b2576 100644 --- a/xml/System.Net.Mail/LinkedResourceCollection.xml +++ b/xml/System.Net.Mail/LinkedResourceCollection.xml @@ -153,12 +153,12 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the occupied. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the occupied. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - This method invokes on all views in this collection. This method is called by the method. You do not need to call it in your application. + This method invokes on all views in this collection. This method is called by the method. You do not need to call it in your application. > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. +> Always call before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. ]]> diff --git a/xml/System.Net.Mail/MailAddressCollection.xml b/xml/System.Net.Mail/MailAddressCollection.xml index 1d408687529..f944f98803b 100644 --- a/xml/System.Net.Mail/MailAddressCollection.xml +++ b/xml/System.Net.Mail/MailAddressCollection.xml @@ -57,7 +57,7 @@ , , and properties return instances of this class that are used to hold the respective email addresses. + The , , and properties return instances of this class that are used to hold the respective email addresses. For details on the mail address formats supported by the class, see the class. diff --git a/xml/System.Net.Mail/MailMessage.xml b/xml/System.Net.Mail/MailMessage.xml index 82527f41995..9e313d47bad 100644 --- a/xml/System.Net.Mail/MailMessage.xml +++ b/xml/System.Net.Mail/MailMessage.xml @@ -60,27 +60,27 @@ ## Remarks Instances of the class are used to construct email messages that are transmitted to an SMTP server for delivery using the class. - The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. + The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. The primary mail message headers and elements for the message may be set using the following properties of the class. |Mail header or part|Property| |-------------------------|--------------| -|Attachments|| -|Blind carbon copies (BCC)|| -|Carbon copies (CC)|| -|Content-Type|| -|Encoding for custom headers|| -|Message body|| -|Priority|| -|Recipient|| -|Reply-To|| -|Sender|| -|Subject|| - - The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: +|Attachments|| +|Blind carbon copies (BCC)|| +|Carbon copies (CC)|| +|Content-Type|| +|Encoding for custom headers|| +|Message body|| +|Priority|| +|Recipient|| +|Reply-To|| +|Sender|| +|Subject|| + + The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - Bcc - Cc @@ -100,11 +100,11 @@ If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. - Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . + Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . - Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. + Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. - After assembling your email message, you can send it by using the or methods. + After assembling your email message, you can send it by using the or methods. @@ -375,12 +375,12 @@ |Parameter|Property| |---------------|--------------| -|`from`|| -|`to`|| -|`subject`|| -|`body`|| +|`from`|| +|`to`|| +|`subject`|| +|`body`|| - By default, the subject and content are assumed to use the default encoding based on local computer settings. Use the and properties to specify different encodings. + By default, the subject and content are assumed to use the default encoding based on local computer settings. Use the and properties to specify different encodings. @@ -452,7 +452,7 @@ ## Remarks Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. + To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. @@ -510,7 +510,7 @@ ## Remarks Use the collection returned by the property to add an attachment, such as a file or the contents of a , to this . - Create an that contains or references the data to be attached, and then add the to the collection returned by . + Create an that contains or references the data to be attached, and then add the to the collection returned by . @@ -568,12 +568,12 @@ ## Remarks To add a BCC recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by the property. - When recipients view an email message, the addresses are usually not displayed. + When recipients view an email message, the addresses are usually not displayed. ## Examples - The following code example demonstrates adding an address to the address collection. + The following code example demonstrates adding an address to the address collection. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet9"::: @@ -624,7 +624,7 @@ of the content is "text/plain". Specify the encoding used for the body with the property. + The of the content is "text/plain". Specify the encoding used for the body with the property. If the body content is available in alternative formats that provide richer presentation options for the recipients, you can specify alternate views for the body content by using the property. For example, an application might choose to send both the plain text body and an HTML version of the message body. Email readers that can display HTML can present the HTML version of the body to the recipient, while readers that cannot display HTML will display the plain text version of the message instead. @@ -699,7 +699,7 @@ ## Remarks The value specified for the property sets the character set field in the Content-Type header. The default character set is `"us-ascii"`. - If you set the property to , , or , the Framework selects a of for this . + If you set the property to , , or , the Framework selects a of for this . @@ -804,7 +804,7 @@ ## Examples - The following code example demonstrates adding an address to the address collection. + The following code example demonstrates adding an address to the address collection. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet10"::: @@ -921,10 +921,10 @@ method when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + Call the method when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . +> Always call before you release your last reference to the . @@ -1100,9 +1100,9 @@ property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + The property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - Bcc @@ -1136,23 +1136,23 @@ If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. - The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. + The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. The primary mail message headers and elements for the message may be set using the following properties of the class. |Mail header or part|Property| |-------------------------|--------------| -|Attachments|| -|Blind carbon copies (BCC)|| -|Carbon copies (CC)|| -|Content-Type|| -|Encoding for custom headers|| -|Message body|| -|Priority|| -|Recipient|| -|Reply-To|| -|Sender|| -|Subject|| +|Attachments|| +|Blind carbon copies (BCC)|| +|Carbon copies (CC)|| +|Content-Type|| +|Encoding for custom headers|| +|Message body|| +|Priority|| +|Recipient|| +|Reply-To|| +|Sender|| +|Subject|| @@ -1214,7 +1214,7 @@ property defaults to . + The value of the property defaults to . SMTP messages consist of headers and body parts. The IETF RFCs for SMTP restrict the header and body part names to be ASCII. However, the IETF RFCs allow header and body part values to contain Unicode characters. In any particular value, if non-ASCII characters exist, then the value is encoded using a combination of character encoding (UTF8 or Shift-JIS, for example) followed by byte encoding ( or for example). The result is usually that only ASCII characters are in the network transmission stream. @@ -1380,7 +1380,7 @@ property to indicate an address other than the address to use to reply to this message. + Use the property to indicate an address other than the address to use to reply to this message. ]]> @@ -1427,7 +1427,7 @@ property to indicate the list of addresses other than the address to use to reply to this message. + Use the property to indicate the list of addresses other than the address to use to reply to this message. The property replaces the property that only allows a single address to reply to. @@ -1595,7 +1595,7 @@ of , use . + If a mail agent has difficulty with a of , use . diff --git a/xml/System.Net.Mail/SendCompletedEventHandler.xml b/xml/System.Net.Mail/SendCompletedEventHandler.xml index dd0e1b63a3f..432916d70fa 100644 --- a/xml/System.Net.Mail/SendCompletedEventHandler.xml +++ b/xml/System.Net.Mail/SendCompletedEventHandler.xml @@ -56,13 +56,13 @@ delegate is used to handle events that occur when the class finishes asynchronously sending an email message using the method. + The delegate is used to handle events that occur when the class finishes asynchronously sending an email message using the method. ## Examples The following code example demonstrates sending an email message asynchronously. It uses a to invoke the `SendCompletedCallback` method to handle events. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet1"::: diff --git a/xml/System.Net.Mail/SmtpClient.xml b/xml/System.Net.Mail/SmtpClient.xml index 028dee27559..66e72002660 100644 --- a/xml/System.Net.Mail/SmtpClient.xml +++ b/xml/System.Net.Mail/SmtpClient.xml @@ -87,20 +87,20 @@ The classes shown in the following table are used to construct email messages th To construct and send an email message by using , you must specify the following information: -- The SMTP host server that you use to send email. See the and properties. +- The SMTP host server that you use to send email. See the and properties. - Credentials for authentication, if required by the SMTP server. See the property. -- The email address of the sender. See the and methods that take a `from` parameter. Also see the property. -- The email address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. -- The message content. See the and methods that take a `body` parameter. Also see the property. +- The email address of the sender. See the and methods that take a `from` parameter. Also see the property. +- The email address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. +- The message content. See the and methods that take a `body` parameter. Also see the property. To include an attachment with an email message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the email reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property. In .NET Framework, you can use the application or machine configuration files to specify default host, port, and credentials values for all objects. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). .NET Core does not support setting defaults. As a workaround, you must set the relevant properties on directly. - To send the email message and block while waiting for the email to be transmitted to the SMTP server, use one of the synchronous methods. To allow your program's main thread to continue executing while the email is transmitted, use one of the asynchronous methods. The event is raised when a operation completes. To receive this event, you must add a delegate to . The delegate must reference a callback method that handles notification of events. To cancel an asynchronous email transmission, use the method. + To send the email message and block while waiting for the email to be transmitted to the SMTP server, use one of the synchronous methods. To allow your program's main thread to continue executing while the email is transmitted, use one of the asynchronous methods. The event is raised when a operation completes. To receive this event, you must add a delegate to . The delegate must reference a callback method that handles notification of events. To cancel an asynchronous email transmission, use the method. > [!NOTE] -> If there is an email transmission in progress and you call or again, you will receive an . +> If there is an email transmission in progress and you call or again, you will receive an . The connection established by the current instance of the class to the SMTP server may be re-used if an application wishes to send multiple messages to the same SMTP server. This is particularly useful when authentication or encryption are used establish a connection to the SMTP server. The process of authenticating and establishing a TLS session can be expensive operations. A requirement to re-establish a connection for each message when sending a large quantity of email to the same SMTP server could have a significant impact on performance. There are a number of high-volume email applications that send email status updates, newsletter distributions, or email alerts. Also many email client applications support an off-line mode where users can compose many email messages that are sent later when a connection to the SMTP server is established. It is typical for an email client to send all SMTP messages to a specific SMTP server (provided by the Internet service provider) that then forwards this email to other SMTP servers. @@ -108,9 +108,9 @@ To include an attachment with an email message, first create the attachment by u When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client. - The class has no `Finalize` method, so an application must call to explicitly free up resources. The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. + The class has no `Finalize` method, so an application must call to explicitly free up resources. The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. ## Examples @@ -176,7 +176,7 @@ The following code example demonstrates sending an email message asynchronously. , , and properties for the new by using the settings in the application or machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). + This constructor initializes the , , and properties for the new by using the settings in the application or machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). @@ -234,7 +234,7 @@ The following code example demonstrates sending an email message asynchronously. property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. + The `host` parameter is used to initialize the value of the property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using constructors or properties, this information overrides the configuration file settings. @@ -294,7 +294,7 @@ The following code example demonstrates sending an email message asynchronously. and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. + The `host` and `port` parameters set the value of the and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using constructors or properties, this information overrides the configuration file settings. @@ -362,7 +362,7 @@ The following code example demonstrates sending an email message asynchronously. Client certificates are, by default, optional; however, the server configuration might require that the client present a valid certificate as part of the initial connection negotiation. > [!NOTE] -> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. +> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. @@ -419,7 +419,7 @@ The following code example demonstrates sending an email message asynchronously. to `true` instead of setting this property. If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. + Some SMTP servers require that the client be authenticated before the server will send email on its behalf. To use your default network credentials, you can set the to `true` instead of setting this property. If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. Credentials information can also be specified using the application and machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using the property, this information overrides the configuration file settings. @@ -536,7 +536,7 @@ The following code example demonstrates sending an email message asynchronously. - Moving the email into the pickup directory for IIS, which then delivers the message. -- Moving the email to a directory specified by for later delivery by another application. +- Moving the email to a directory specified by for later delivery by another application. The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. @@ -566,7 +566,7 @@ The following code example demonstrates sending an email message asynchronously. When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client. - The methods iterates through all established connections and send a QUIT message to each SMTP server, followed by gracefully ending the TCP connection. These methods also release the unmanaged resources used by the and optionally dispose of the managed resources. + The methods iterates through all established connections and send a QUIT message to each SMTP server, followed by gracefully ending the TCP connection. These methods also release the unmanaged resources used by the and optionally dispose of the managed resources. ]]> @@ -622,18 +622,18 @@ The following code example demonstrates sending an email message asynchronously. When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client. - Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called. + Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called. - The class has no `Finalize` method. So an application must call to explicitly free up resources. + The class has no `Finalize` method. So an application must call to explicitly free up resources. - The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the underlying . + The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the underlying . - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory. ]]> @@ -690,18 +690,18 @@ The following code example demonstrates sending an email message asynchronously. When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client. - Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called. + Calling the method on a object that is executing an asynchronous operation will cancel the send operation as though the method had been called. - The class has no `Finalize` method. So an application must call to explicitly free up resources. + The class has no `Finalize` method. So an application must call to explicitly free up resources. - The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. + The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory. +> Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed so the garbage collector can reclaim the memory. ]]> @@ -758,10 +758,10 @@ The following code example demonstrates sending an email message asynchronously. An alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTP/SSL, SMTP over SSL, or SMTPS and by default uses port 465. This alternate connection method using SSL is not currently supported. - You can use to specify which client certificates should be used to establish the SSL connection. The allows you to reject the certificate provided by the SMTP server. The property allows you to specify the version of the SSL protocol to use. + You can use to specify which client certificates should be used to establish the SSL connection. The allows you to reject the certificate provided by the SMTP server. The property allows you to specify the version of the SSL protocol to use. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . @@ -899,9 +899,9 @@ The following code example demonstrates sending an email message asynchronously. class can override the method to perform additional tasks when the event occurs. + Classes that inherit from the class can override the method to perform additional tasks when the event occurs. - also allows derived classes to handle without attaching a delegate. This is the preferred technique for handling in a derived class. + also allows derived classes to handle without attaching a delegate. This is the preferred technique for handling in a derived class. ]]> @@ -1102,18 +1102,18 @@ The following code example demonstrates sending an email message asynchronously. ## Remarks This method blocks while the email is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses. - Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. + Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. You cannot call this method if there is a message being sent asynchronously. - If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. + If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. - When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. + When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ## Examples The following code example demonstrates using this method. @@ -1235,18 +1235,18 @@ The following code example demonstrates sending an email message asynchronously. ## Remarks This method blocks while the email is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses. - Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. + Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. You cannot call this method if there is a message being sent asynchronously. - If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. + If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. - When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. + When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ]]> @@ -1362,26 +1362,26 @@ The following code example demonstrates sending an email message asynchronously. event. You can cancel a operation by calling the method. + To receive notification when the email has been sent or the operation has been canceled, add an event handler to the event. You can cancel a operation by calling the method. - After calling , you must wait for the email transmission to complete before attempting to send another email message using or . + After calling , you must wait for the email transmission to complete before attempting to send another email message using or . - Before calling this method, the and must be set through the configuration files by setting the relevant properties, or by passing this information into the constructor. + Before calling this method, the and must be set through the configuration files by setting the relevant properties, or by passing this information into the constructor. - If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. + If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. - When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. + When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. Your application can detect a server certificate validation error by examining the property passed into the delegate. - The property does not have any effect on a call. + The property does not have any effect on a call. - To send mail and block while it is transmitted to the SMTP server, use one of the methods. + To send mail and block while it is transmitted to the SMTP server, use one of the methods. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ## Examples The following code example demonstrates calling this method. @@ -1508,26 +1508,26 @@ The following code example demonstrates sending an email message asynchronously. event. You can cancel a operation by calling the method. + To receive notification when the email has been sent or the operation has been canceled, add an event handler to the event. You can cancel a operation by calling the method. - After calling , you must wait for the email transmission to complete before attempting to send another email message using or . + After calling , you must wait for the email transmission to complete before attempting to send another email message using or . - Before calling this method, the and properties must be set either through the configuration files or by setting the properties or passing this information into the constructor. + Before calling this method, the and properties must be set either through the configuration files or by setting the properties or passing this information into the constructor. - If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or property. + If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or property. If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. - When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. + When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. Your application can detect a server certificate validation error by examining the property passed into the delegate. - The property does not have any effect on a call. + The property does not have any effect on a call. - To send mail and block while it is transmitted to the SMTP server, use one of the methods. + To send mail and block while it is transmitted to the SMTP server, use one of the methods. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ]]> @@ -1624,7 +1624,7 @@ The following code example demonstrates sending an email message asynchronously. method to cancel a pending operation. If there is mail waiting to be sent, this method releases resources used to store the mail. If there is no mail waiting to be sent, this method does nothing. + Use the method to cancel a pending operation. If there is mail waiting to be sent, this method releases resources used to store the mail. If there is no mail waiting to be sent, this method does nothing. @@ -1682,7 +1682,7 @@ The following code example demonstrates sending an email message asynchronously. event is raised each time an email message is sent asynchronously when the send operation completes. To send an email message asynchronously, use the methods. + The event is raised each time an email message is sent asynchronously when the send operation completes. To send an email message asynchronously, use the methods. is the delegate for . The class provides the event handler with event data. @@ -2303,9 +2303,9 @@ The following code example demonstrates sending an email message asynchronously. method block until the operation completes. If you set the property to a positive value, and a operation cannot complete in the allotted time, the class throws an exception. + By default, calls to the method block until the operation completes. If you set the property to a positive value, and a operation cannot complete in the allotted time, the class throws an exception. - To send a message and continue executing in the application thread, use the method. + To send a message and continue executing in the application thread, use the method. diff --git a/xml/System.Net.Mail/SmtpPermission.xml b/xml/System.Net.Mail/SmtpPermission.xml index b4f1bf0e3df..18d2f49fb5e 100644 --- a/xml/System.Net.Mail/SmtpPermission.xml +++ b/xml/System.Net.Mail/SmtpPermission.xml @@ -601,7 +601,7 @@ method returns a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The method returns a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Net.Mail/SmtpPermissionAttribute.xml b/xml/System.Net.Mail/SmtpPermissionAttribute.xml index d351ad37c9b..a48bef1523a 100644 --- a/xml/System.Net.Mail/SmtpPermissionAttribute.xml +++ b/xml/System.Net.Mail/SmtpPermissionAttribute.xml @@ -48,16 +48,16 @@ Controls access to Simple Mail Transport Protocol (SMTP) servers. - and classes control access to SMTP host computers. The class demands an when sending electronic mail to the SMTP host for delivery. - - The enumeration specifies the level of access controlled by an instance of this permission. - + The and classes control access to SMTP host computers. The class demands an when sending electronic mail to the SMTP host for delivery. + + The enumeration specifies the level of access controlled by an instance of this permission. + ]]> @@ -100,11 +100,11 @@ One of the values that specifies the permission behavior. Initializes a new instance of the class. - @@ -153,11 +153,11 @@ Gets or sets the level of access to SMTP servers controlled by the attribute. A value. Valid values are "Connect" and "None". - method will throw an when called by the system. - + method will throw an when called by the system. + ]]> @@ -195,13 +195,13 @@ Creates a permission object that can be stored with the in an assembly's metadata. An instance. - diff --git a/xml/System.Net.Mail/SmtpStatusCode.xml b/xml/System.Net.Mail/SmtpStatusCode.xml index 45f0a62aa50..2a29b1fdee3 100644 --- a/xml/System.Net.Mail/SmtpStatusCode.xml +++ b/xml/System.Net.Mail/SmtpStatusCode.xml @@ -47,7 +47,7 @@ enumeration specify reply status values sent by a Simple Mail Transfer Protocol (SMTP) server. The and classes contain properties that return values. + The values in the enumeration specify reply status values sent by a Simple Mail Transfer Protocol (SMTP) server. The and classes contain properties that return values. SMTP is defined in RFC 2821 available at [https://www.ietf.org](https://www.ietf.org/). diff --git a/xml/System.Net.Mime/ContentDisposition.xml b/xml/System.Net.Mime/ContentDisposition.xml index 35154929ed0..b08cd1c27f8 100644 --- a/xml/System.Net.Mime/ContentDisposition.xml +++ b/xml/System.Net.Mime/ContentDisposition.xml @@ -59,11 +59,11 @@ Email messages are created using instances of the class. Instances of the class are used to add attachments to email messages. To modify the for an attachment, get the instance from the property. - Content to be displayed as part of the message body has the disposition type of . Content that is not displayed but is attached in a separate file has the disposition type of . Use the property to control the disposition type for the attachment associated with an instance of . + Content to be displayed as part of the message body has the disposition type of . Content that is not displayed but is attached in a separate file has the disposition type of . Use the property to control the disposition type for the attachment associated with an instance of . For file attachments, you can use the properties of the to set the file size, as well as the date the file was created, last read, and last modified. For all attachments, you can set a recommended file name in the event that the attachment is stored on the receiving computer. - The method returns the Content-Disposition header. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). + The method returns the Content-Disposition header. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -711,7 +711,7 @@ ## Remarks The property is used to send time stamp information with a file being sent in an email message. This value sets the Read-Date parameter in the Content-Disposition header sent with the email message. - The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment by using the property. + The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment by using the property. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -826,7 +826,7 @@ method is the Content-Disposition header. + The string returned by the method is the Content-Disposition header. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). diff --git a/xml/System.Net.Mime/ContentType.xml b/xml/System.Net.Mime/ContentType.xml index c5701bb9f98..55c61056d1d 100644 --- a/xml/System.Net.Mime/ContentType.xml +++ b/xml/System.Net.Mime/ContentType.xml @@ -61,7 +61,7 @@ ## Examples - The following code example sends an email message with an attachment and displays the properties for the attachment. + The following code example sends an email message with an attachment and displays the properties for the attachment. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: @@ -242,7 +242,7 @@ parameter is "`-----boundary---0`". + In the following example of a Content-Type header, the value of the parameter is "`-----boundary---0`". `content-type: multipart/mixed; boundary=-----boundary---0` @@ -537,7 +537,7 @@ A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1, available at [https://www.ietf.org](https://www.ietf.org/). - When specifying content for a as a or , you can use to set the name of the file that stores the content on the recipient's system. + When specifying content for a as a or , you can use to set the name of the file that stores the content on the recipient's system. @@ -652,7 +652,7 @@ method contains the string used to create this , if one was specified and no property values have been changed. If no string was specified, or one or more property values have changed since this was created, the value of is a string in the format of a Content-Type header that is composed using the current property values. The string does not include the `"Content-type:"` prefix. + The value of the method contains the string used to create this , if one was specified and no property values have been changed. If no string was specified, or one or more property values have changed since this was created, the value of is a string in the format of a Content-Type header that is composed using the current property values. The string does not include the `"Content-type:"` prefix. The syntax of the Content-Type header is described in RFC 2045 Section 5.1, available at [https://www.ietf.org](https://www.ietf.org/). diff --git a/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml index bfcb7900a8d..d6572e1ada9 100644 --- a/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml @@ -408,11 +408,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> @@ -612,11 +612,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net.NetworkInformation/IPAddressCollection.xml b/xml/System.Net.NetworkInformation/IPAddressCollection.xml index 08c8159a713..5ff0dcea725 100644 --- a/xml/System.Net.NetworkInformation/IPAddressCollection.xml +++ b/xml/System.Net.NetworkInformation/IPAddressCollection.xml @@ -408,11 +408,11 @@ The number of elements in this method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> @@ -612,11 +612,11 @@ The number of elements in this method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml index 6b9d3a8a433..471ee2fd77f 100644 --- a/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml @@ -377,11 +377,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> @@ -581,11 +581,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml index eeacc8ebbaf..31a8a9488cb 100644 --- a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml +++ b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml @@ -176,9 +176,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -351,11 +351,11 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method ends a pending asynchronous request to retrieve the stable unicast IP address table. + The method ends a pending asynchronous request to retrieve the stable unicast IP address table. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -417,7 +417,7 @@ state. You can check the state of a connection by calling . + The objects returned by this method include connections in all TCP states except the state. You can check the state of a connection by calling . The TCP protocol is defined in IETF RFC 793. Note that the objects returned by this method reflect the connections as of the time the array is created. This information is not updated dynamically. @@ -1220,9 +1220,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -1281,9 +1281,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.Net.NetworkInformation/IPGlobalStatistics.xml b/xml/System.Net.NetworkInformation/IPGlobalStatistics.xml index 1882929f3b5..9a6bf584d44 100644 --- a/xml/System.Net.NetworkInformation/IPGlobalStatistics.xml +++ b/xml/System.Net.NetworkInformation/IPGlobalStatistics.xml @@ -49,7 +49,7 @@ and methods to return IP traffic information. + This class is used by the and methods to return IP traffic information. The Internet protocol is used to move IP packets from a source computer to a destination computer. IP also handles dividing a packet that is too large into multiple packets that are small enough for transport, in a process known as fragmentation. @@ -59,7 +59,7 @@ ## Examples The following code example displays IP statistics. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet1"::: ]]> @@ -339,7 +339,7 @@ ## Remarks The data returned by this property includes addresses of pseudo network interfaces such as tunnels. - If this instance was obtained by calling , this property returns the number of IPv4 addresses assigned to the local computer. Similarly, if this instance was obtained by calling , this property returns the number of IPv6 addresses assigned to the local computer. + If this instance was obtained by calling , this property returns the number of IPv4 addresses assigned to the local computer. Similarly, if this instance was obtained by calling , this property returns the number of IPv6 addresses assigned to the local computer. ]]> diff --git a/xml/System.Net.NetworkInformation/IPInterfaceProperties.xml b/xml/System.Net.NetworkInformation/IPInterfaceProperties.xml index 2da24245079..9ee8b5597b8 100644 --- a/xml/System.Net.NetworkInformation/IPInterfaceProperties.xml +++ b/xml/System.Net.NetworkInformation/IPInterfaceProperties.xml @@ -55,15 +55,15 @@ method. + This class provides access to configuration and address information for network interfaces that support IPv4 or IPv6. You do not create instances of this class; they are returned by the method. - To access IPv4-specific properties, use the object returned by the method. To access IPv6-specific properties, use the object returned by the method. + To access IPv4-specific properties, use the object returned by the method. To access IPv6-specific properties, use the object returned by the method. ## Examples The following code example displays address information. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet8"::: ]]> @@ -375,7 +375,7 @@ , and must resolve the unqualified host name "www", the FQDN to query is "www.contoso.com". + The DNS suffix identifies the domain name (for example, "contoso.com") that is appended to an unqualified host name to obtain a fully qualified domain name (FQDN) suitable for a DNS name query. For example, if the local machine has "contoso.com" as its , and must resolve the unqualified host name "www", the FQDN to query is "www.contoso.com". @@ -496,8 +496,8 @@ class documentation. Note that the object returned by the method reflects the configuration as of the time the object is created. This information is not updated dynamically. - A is thrown if the interface does not support the IPv4 protocol, therefore it's recommended to check IPv4 support calling on the originating instance before querying the IPv4 properties. + For a detailed description of the information available for an interface that supports IPv4, see the class documentation. Note that the object returned by the method reflects the configuration as of the time the object is created. This information is not updated dynamically. + A is thrown if the interface does not support the IPv4 protocol, therefore it's recommended to check IPv4 support calling on the originating instance before querying the IPv4 properties. ]]> @@ -548,8 +548,8 @@ documentation. Note that the object returned by the method reflects the configuration as of the time the object is created. This information is not updated dynamically. - A is thrown if the interface does not support the IPv6 protocol, therefore it's recommended to check IPv6 support calling on the originating instance before querying the IPv6 properties. + For a detailed description of the information available for an interface that supports IPv6, see the documentation. Note that the object returned by the method reflects the configuration as of the time the object is created. This information is not updated dynamically. + A is thrown if the interface does not support the IPv6 protocol, therefore it's recommended to check IPv6 support calling on the originating instance before querying the IPv6 properties. ]]> diff --git a/xml/System.Net.NetworkInformation/IPInterfaceStatistics.xml b/xml/System.Net.NetworkInformation/IPInterfaceStatistics.xml index a6b435e6290..9203e4a69e5 100644 --- a/xml/System.Net.NetworkInformation/IPInterfaceStatistics.xml +++ b/xml/System.Net.NetworkInformation/IPInterfaceStatistics.xml @@ -45,11 +45,11 @@ Provides Internet Protocol (IP) statistical data for an network interface on the local computer. - method to return network traffic information for an interface. - + method to return network traffic information for an interface. + ]]> @@ -89,11 +89,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -219,11 +219,11 @@ Gets the number of incoming packets that were discarded. The total number of incoming packets that were discarded. - @@ -267,11 +267,11 @@ Gets the number of incoming packets with errors. The total number of incoming packets with errors. - @@ -321,11 +321,11 @@ Gets the number of incoming packets with an unknown protocol that were received on the interface. The total number of incoming packets with an unknown protocol that were received on the interface. - @@ -369,11 +369,11 @@ Gets the number of non-unicast packets that were received on the interface. The total number of incoming non-unicast packets received on the interface. - @@ -423,11 +423,11 @@ Gets the number of non-unicast packets that were sent on the interface. The total number of non-unicast packets that were sent on the interface. - @@ -489,11 +489,11 @@ Gets the number of outgoing packets that were discarded. The total number of outgoing packets that were discarded. - @@ -537,11 +537,11 @@ Gets the number of outgoing packets with errors. The total number of outgoing packets with errors. - @@ -626,11 +626,11 @@ Gets the number of unicast packets that were received on the interface. The total number of unicast packets that were received on the interface. - @@ -674,11 +674,11 @@ Gets the number of unicast packets that were sent on the interface. The total number of unicast packets that were sent on the interface. - diff --git a/xml/System.Net.NetworkInformation/IPStatus.xml b/xml/System.Net.NetworkInformation/IPStatus.xml index fcdd4c66586..b1ea1f476f1 100644 --- a/xml/System.Net.NetworkInformation/IPStatus.xml +++ b/xml/System.Net.NetworkInformation/IPStatus.xml @@ -48,7 +48,7 @@ class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. + The class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. > [!WARNING] > The DestinationProhibited and DestinationProtocolUnreachable enumeration values have the same numeric value. This is possible because DestinationProhibited applies only to IPv6 and DestinationProtocolUnreachable applies only to IPv4. diff --git a/xml/System.Net.NetworkInformation/IPv4InterfaceProperties.xml b/xml/System.Net.NetworkInformation/IPv4InterfaceProperties.xml index c469cb2f17d..cd66b6d28cc 100644 --- a/xml/System.Net.NetworkInformation/IPv4InterfaceProperties.xml +++ b/xml/System.Net.NetworkInformation/IPv4InterfaceProperties.xml @@ -49,15 +49,15 @@ method. + This class provides access to configuration and address information for network interfaces that support IPv4. You do not create instances of this class; they are returned by the method. - For IPV6 properties, see . + For IPV6 properties, see . ## Examples - The following code example gets an object and displays its data. - + The following code example gets an object and displays its data. + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet48"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.vb" id="Snippet48"::: diff --git a/xml/System.Net.NetworkInformation/IPv4InterfaceStatistics.xml b/xml/System.Net.NetworkInformation/IPv4InterfaceStatistics.xml index 7c99141074f..762949b7856 100644 --- a/xml/System.Net.NetworkInformation/IPv4InterfaceStatistics.xml +++ b/xml/System.Net.NetworkInformation/IPv4InterfaceStatistics.xml @@ -45,11 +45,11 @@ Provides statistical data for a network interface on the local computer. - method to return network traffic information for an interface. - + method to return network traffic information for an interface. + ]]> @@ -95,11 +95,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -225,11 +225,11 @@ Gets the number of incoming packets that were discarded. An value that specifies the total number of discarded incoming packets. - @@ -273,11 +273,11 @@ Gets the number of incoming packets with errors. An value that specifies the total number of incoming packets with errors. - @@ -321,11 +321,11 @@ Gets the number of incoming packets with an unknown protocol that were received on the interface. An value that specifies the total number of incoming packets with an unknown protocol. - @@ -369,11 +369,11 @@ Gets the number of non-unicast packets that were received on the interface. An value that specifies the total number of non-unicast packets that were received on the interface. - @@ -417,11 +417,11 @@ Gets the number of non-unicast packets that were sent on the interface. An value that specifies the total number of non-unicast packets that were sent on the interface. - @@ -483,11 +483,11 @@ Gets the number of outgoing packets that were discarded. An value that specifies the total number of discarded outgoing packets. - @@ -531,11 +531,11 @@ Gets the number of outgoing packets with errors. An value that specifies the total number of outgoing packets with errors. - @@ -620,11 +620,11 @@ Gets the number of unicast packets that were received on the interface. An value that specifies the total number of unicast packets that were received on the interface. - @@ -668,11 +668,11 @@ Gets the number of unicast packets that were sent on the interface. An value that specifies the total number of unicast packets that were sent on the interface. - diff --git a/xml/System.Net.NetworkInformation/IPv6InterfaceProperties.xml b/xml/System.Net.NetworkInformation/IPv6InterfaceProperties.xml index 4976c49756a..b0e58976d44 100644 --- a/xml/System.Net.NetworkInformation/IPv6InterfaceProperties.xml +++ b/xml/System.Net.NetworkInformation/IPv6InterfaceProperties.xml @@ -49,9 +49,9 @@ method. + This class provides access to configuration and address information for network interfaces that support IPv6. You do not create instances of this class; they are returned by the method. - For IPV4 properties, see . + For IPV4 properties, see . diff --git a/xml/System.Net.NetworkInformation/IcmpV4Statistics.xml b/xml/System.Net.NetworkInformation/IcmpV4Statistics.xml index b937a03e68f..372fc160409 100644 --- a/xml/System.Net.NetworkInformation/IcmpV4Statistics.xml +++ b/xml/System.Net.NetworkInformation/IcmpV4Statistics.xml @@ -51,13 +51,13 @@ ## Remarks ICMPv4 is a set of error and informational messages for use with Internet Protocol version 4. ICMP version 4 is defined in IETF RFC 792. - This class is used by the method to return ICMPv4 traffic information. + This class is used by the method to return ICMPv4 traffic information. ## Examples The following example displays the current ICMPv4 statistics. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet6"::: ]]> diff --git a/xml/System.Net.NetworkInformation/IcmpV6Statistics.xml b/xml/System.Net.NetworkInformation/IcmpV6Statistics.xml index 7546b06e01a..a258a187b7c 100644 --- a/xml/System.Net.NetworkInformation/IcmpV6Statistics.xml +++ b/xml/System.Net.NetworkInformation/IcmpV6Statistics.xml @@ -49,7 +49,7 @@ method to return ICMPV6 traffic information. + ICMPV6 is a set of error and informational messages for use with Internet Protocol version 6 (IPv6). This class is used by the method to return ICMPV6 traffic information. The properties in this class correlate to the Management Information Base objects for ICMPv6 defined in IETF RFC 2466. ICMPv6 is defined in RFC 2463. diff --git a/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml b/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml index 35207d0cb16..3ee1ff995f3 100644 --- a/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml +++ b/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml @@ -155,7 +155,7 @@ to determine the preferred address. + Use the value returned by this property to determine how long the preferred address remains valid. Whenever possible, applications should use a preferred address. Use to determine the preferred address. ]]> @@ -211,7 +211,7 @@ to determine the preferred address. + Use the value returned by this property to determine whether this address can be used by your application. Whenever possible, applications should use a preferred address. Use to determine the preferred address. ]]> diff --git a/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml index 5db994d266e..f5e09124fa0 100644 --- a/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml @@ -408,11 +408,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> @@ -612,11 +612,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml b/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml index 77d93eb943c..2a10feee35e 100644 --- a/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml +++ b/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml @@ -492,7 +492,7 @@ constructor. + An unrestricted permission is created using the constructor. ]]> @@ -581,7 +581,7 @@ method returns a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + The method returns a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Net.NetworkInformation/NetworkInterface.xml b/xml/System.Net.NetworkInformation/NetworkInterface.xml index fb5f38283d6..81623f8fb79 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterface.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterface.xml @@ -66,7 +66,7 @@ method returns an array that contains one instance of this class for each network interface on the local computer. + This class encapsulates data for network interfaces, also known as adapters, on the local computer. You do not create instances of this class; the method returns an array that contains one instance of this class for each network interface on the local computer. diff --git a/xml/System.Net.NetworkInformation/NetworkInterfaceComponent.xml b/xml/System.Net.NetworkInformation/NetworkInterfaceComponent.xml index 1e23ae9292c..69601fd2c3a 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterfaceComponent.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterfaceComponent.xml @@ -48,13 +48,13 @@ method to specify the Internet Protocol version supported by a network interface. + The values in this enumeration are used by the method to specify the Internet Protocol version supported by a network interface. ## Examples The following code example checks whether a network interface supports IPv4. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet48"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.vb" id="Snippet48"::: diff --git a/xml/System.Net.NetworkInformation/PhysicalAddress.xml b/xml/System.Net.NetworkInformation/PhysicalAddress.xml index 48de05d0971..32a63330a69 100644 --- a/xml/System.Net.NetworkInformation/PhysicalAddress.xml +++ b/xml/System.Net.NetworkInformation/PhysicalAddress.xml @@ -57,7 +57,7 @@ ## Remarks The MAC address, or physical address, is a hardware address that uniquely identifies each node, such as a computer or printer, on a network. - Instances of this class are returned by the method. + Instances of this class are returned by the method. @@ -113,9 +113,9 @@ method. + In common scenarios, applications do not need to call this constructor; instances of this class are returned by the method. - Note that you can also use the method to create a new instance of . + Note that you can also use the method to create a new instance of . @@ -329,7 +329,7 @@ method returns if you specify `null` address. + The method returns if you specify `null` address. @@ -397,12 +397,12 @@ `f0-e1-d2-c3-b4-a5` - Use the method to retrieve the address from an existing instance. + Use the method to retrieve the address from an existing instance. ## Examples - The following code example creates a instance by calling the method. + The following code example creates a instance by calling the method. :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/PhysicalAddress/Overview/physaddresstester.cs" id="Snippet6"::: @@ -484,12 +484,12 @@ In .NET Framework, an address that contains `f0-e1-d2-c3-b4-a5` will fail to parse and throw an exception. - Use the method to retrieve the address from an existing instance. + Use the method to retrieve the address from an existing instance. ## Examples - The following code example creates a instance by calling the method. + The following code example creates a instance by calling the method. :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/PhysicalAddress/Overview/physaddresstester.cs" id="Snippet5"::: @@ -614,7 +614,7 @@ In .NET Framework, an address that contains `f0-e1-d2-c3-b4-a5` will fail to par `f0-e1-d2-c3-b4-a5` - Use the method to retrieve the address from an existing instance. + Use the method to retrieve the address from an existing instance. ]]> @@ -679,7 +679,7 @@ In .NET Framework, an address that contains `f0-e1-d2-c3-b4-a5` will fail to par `f0-e1-d2-c3-b4-a5` - Use the method to retrieve the address from an existing instance. + Use the method to retrieve the address from an existing instance. ]]> diff --git a/xml/System.Net.NetworkInformation/Ping.xml b/xml/System.Net.NetworkInformation/Ping.xml index 5f68576ef95..928c0b5eead 100644 --- a/xml/System.Net.NetworkInformation/Ping.xml +++ b/xml/System.Net.NetworkInformation/Ping.xml @@ -74,36 +74,36 @@ Network topology can determine whether can successfully contact a remote host. The presence and configuration of proxies, network address translation (NAT) equipment, or firewalls can prevent from succeeding. A successful indicates only that the remote host can be reached on the network; the presence of higher level services (such as a Web server) on the remote host is not guaranteed. - This class provides functionality similar to the Ping.exe command line tool. The and methods send an Internet Control Message Protocol (ICMP) echo request message to a remote computer and wait for an ICMP echo reply message from that computer. For a detailed description of ICMP messages, see RFC 792, available at [https://www.ietf.org](https://www.ietf.org/). + This class provides functionality similar to the Ping.exe command line tool. The and methods send an Internet Control Message Protocol (ICMP) echo request message to a remote computer and wait for an ICMP echo reply message from that computer. For a detailed description of ICMP messages, see RFC 792, available at [https://www.ietf.org](https://www.ietf.org/). The following types are used with the class and are described in detail below. |**Type name**|**Description**| |-------------------|---------------------| ||Defines status codes that describe the outcome of an ICMP echo request message.| -||Allows you to configure or retrieve the settings that control how many times the request packet can be forwarded (), and whether it can be fragmented ( ).| +||Allows you to configure or retrieve the settings that control how many times the request packet can be forwarded (), and whether it can be fragmented ( ).| ||Contains the results of an ICMP echo request.| ||Thrown if an unrecoverable error occurs.| -||Contains the data associated with events, which are raised when a call completes or is canceled.| -||The delegate that provides the callback method invoked when a call completes or is canceled.| +||Contains the data associated with events, which are raised when a call completes or is canceled.| +||The delegate that provides the callback method invoked when a call completes or is canceled.| - The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. + The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. When sending the request, you must specify the remote computer. You can do this by providing a host name string, an IP address in string format, or an object. You can also specify any of the following types of information: -- Data to accompany the request. Specifying `buffer` allows you to learn the amount of time required for a packet of a particular size to travel to and from the remote host and the maximum transmission unit of the network path. (See the or overloads that take a `buffer` parameter.) +- Data to accompany the request. Specifying `buffer` allows you to learn the amount of time required for a packet of a particular size to travel to and from the remote host and the maximum transmission unit of the network path. (See the or overloads that take a `buffer` parameter.) -- Whether the ICMP Echo packet can be fragmented in transit. (See the property and the or overloads that take an `options` parameter.) +- Whether the ICMP Echo packet can be fragmented in transit. (See the property and the or overloads that take an `options` parameter.) -- How many times routing nodes, such as routers or gateways, can forward the packet before it either reaches the destination computer or is discarded. (See and the or overloads that take an `options` parameter.) +- How many times routing nodes, such as routers or gateways, can forward the packet before it either reaches the destination computer or is discarded. (See and the or overloads that take an `options` parameter.) -- The time limit within which the reply must be received. (See the or overloads that take a `timeout` parameter. +- The time limit within which the reply must be received. (See the or overloads that take a `timeout` parameter. - The class offers both synchronous and asynchronous methods for sending the request. If your application should block while waiting for a reply, use the methods; these methods are synchronous. If your application should not block, use the asynchronous methods. A call to executes in its own thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called for events. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. + The class offers both synchronous and asynchronous methods for sending the request. If your application should block while waiting for a reply, use the methods; these methods are synchronous. If your application should not block, use the asynchronous methods. A call to executes in its own thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called for events. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. - You cannot use the same instance of the class to generate multiple simultaneous ICMP Echo requests. Calling while a call is in progress or calling multiple times before all previous calls have completed causes an . + You cannot use the same instance of the class to generate multiple simultaneous ICMP Echo requests. Calling while a call is in progress or calling multiple times before all previous calls have completed causes an . @@ -252,7 +252,7 @@ method. The public `Dispose()` method invokes the protected method with the `disposing` parameter set to `true`. invokes `Dispose` with `disposing` set to `false`. + This method is called by the public `Dispose()` method and the method. The public `Dispose()` method invokes the protected method with the `disposing` parameter set to `true`. invokes `Dispose` with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this object references. This method invokes the `Dispose()` method of each referenced object. @@ -309,7 +309,7 @@ Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. ]]> @@ -367,7 +367,7 @@ event to get information about the completion status and data collected by a call to one of the methods. The delegate provides the call back method invoked when raises this event. + Applications use the event to get information about the completion status and data collected by a call to one of the methods. The delegate provides the call back method invoked when raises this event. @@ -392,7 +392,7 @@ overloads can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. + The IP address returned by any of the overloads can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. ]]> @@ -446,7 +446,7 @@ ## Remarks This method sends to the host that is specified by `address` a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -512,7 +512,7 @@ ## Remarks This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -583,14 +583,14 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For an example that demonstrates calling a method, see the class overview. + For an example that demonstrates calling a method, see the class overview. ]]> @@ -656,12 +656,12 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For an example that demonstrates calling a method, see the class overview. + For an example that demonstrates calling a method, see the class overview. ]]> @@ -735,9 +735,9 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -820,14 +820,14 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For an example that demonstrates how to call a overload, see the class overview. + For an example that demonstrates how to call a overload, see the class overview. ]]> @@ -911,9 +911,9 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1061,9 +1061,9 @@ > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1163,10 +1163,10 @@ methods. + These methods do not cause your application's main thread to block. If you want to block while waiting for the ICMP echo reply message, use the methods. > [!NOTE] -> The IP address returned by any of the methods can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. +> The IP address returned by any of the methods can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. ]]> @@ -1227,21 +1227,21 @@ method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] -> If your application should block while waiting for a reply, use one of the methods; these methods are synchronous. +> If your application should block while waiting for a reply, use one of the methods; these methods are synchronous. This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For a code example that demonstrates calling a method, see the class overview. + For a code example that demonstrates calling a method, see the class overview. ]]> @@ -1309,21 +1309,21 @@ method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] -> If your application should block while waiting for a reply, use the methods; these methods are synchronous. +> If your application should block while waiting for a reply, use the methods; these methods are synchronous. This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For a code example that demonstrates calling the method, see the class overview. + For a code example that demonstrates calling the method, see the class overview. ]]> @@ -1393,21 +1393,21 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. - If your application should block while waiting for a reply, use the methods; these methods are synchronous. + If your application should block while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For a code example that demonstrates calling a overload, see the class overview. + For a code example that demonstrates calling a overload, see the class overview. ]]> @@ -1479,21 +1479,21 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. - If your application should block while waiting for a reply, use the methods; these methods are synchronous. + If your application should block while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For a code example that demonstrates calling the method, see the class overview. + For a code example that demonstrates calling the method, see the class overview. ]]> @@ -1573,22 +1573,22 @@ method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + This method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] -> If your application blocks while waiting for a reply, use the methods; these methods are synchronous. +> If your application blocks while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - For a code example that demonstrates calling a overload, see the class overview. + For a code example that demonstrates calling a overload, see the class overview. ]]> @@ -1670,21 +1670,21 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object containing a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object containing a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. - If your application should block while waiting for a reply, use the methods; these methods are synchronous. + If your application should block while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - The following code example demonstrates how to call a overload, see the class overview. + The following code example demonstrates how to call a overload, see the class overview. ]]> @@ -1773,23 +1773,23 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. - If your application blocks while waiting for a reply, use the methods; these methods are synchronous. + If your application blocks while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . ## Examples - The following code example demonstrates how to call this method. For an implementation of the callback method, see the method overload example section. + The following code example demonstrates how to call this method. For an implementation of the callback method, see the method overload example section. The following code example requires the following namespaces: @@ -1882,18 +1882,18 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. - If your application should block while waiting for a reply, use the methods; these methods are synchronous. + If your application should block while waiting for a reply, use the methods; these methods are synchronous. If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1963,7 +1963,7 @@ that have not completed. + Call this method to terminate any calls to that have not completed. ]]> @@ -1981,7 +1981,7 @@ methods can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. +The IP address returned by any of the methods can originate from a malicious remote computer. Do not connect to the remote computer using this. Use DNS to determine the IP address of the machine to which you want to connect. ]]> @@ -2033,7 +2033,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2092,7 +2092,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2153,7 +2153,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2214,7 +2214,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2279,7 +2279,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2346,7 +2346,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2427,7 +2427,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> @@ -2504,7 +2504,7 @@ The IP address returned by any of the > object will complete after the ICMP packet has been sent and the response has been received. + This operation will not block. The returned > object will complete after the ICMP packet has been sent and the response has been received. ]]> diff --git a/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml b/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml index 15384d868fc..24ea5bc7a90 100644 --- a/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml +++ b/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml @@ -54,7 +54,7 @@ method that is called when a call completes. The methods send an Internet Control Message Protocol (ICMP) echo request asynchronously and wait for a corresponding ICMP echo reply message. The property contains the results of the ICMP echo request. + Instances of this class are passed to a method that is called when a call completes. The methods send an Internet Control Message Protocol (ICMP) echo request asynchronously and wait for a corresponding ICMP echo reply message. The property contains the results of the ICMP echo request. @@ -116,7 +116,7 @@ is not , you should not use the values that are returned by the , , and properties. The and properties will return zero, and the property will return `null`. + If the value of is not , you should not use the values that are returned by the , , and properties. The and properties will return zero, and the property will return `null`. diff --git a/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml b/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml index c8a1663cdae..6a46f122983 100644 --- a/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml +++ b/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml @@ -56,7 +56,7 @@ call is available to the method invoked by this delegate in the property. + User data that is specified in a call is available to the method invoked by this delegate in the property. diff --git a/xml/System.Net.NetworkInformation/PingOptions.xml b/xml/System.Net.NetworkInformation/PingOptions.xml index 6983d99d737..cd831673a60 100644 --- a/xml/System.Net.NetworkInformation/PingOptions.xml +++ b/xml/System.Net.NetworkInformation/PingOptions.xml @@ -49,15 +49,15 @@ class provides the and properties to control how Internet Control Message Protocol (ICMP) echo request packets are transmitted. + The class provides the and properties to control how Internet Control Message Protocol (ICMP) echo request packets are transmitted. The property specifies the Time to Live for packets sent by the class. This value indicates the number of routing nodes that can forward a packet before it is discarded. Setting this option is useful if you want to test the number of forwards, also known as hops, are required to send a packet from a source computer to a destination computer. The property controls whether data sent to a remote host can be divided into multiple packets. This option is useful if you want to test the maximum transmission unit (MTU) of the routers and gateways used to transmit the packet. - Instances of the class are passed to the and methods, and the class returns instances of via the property. + Instances of the class are passed to the and methods, and the class returns instances of via the property. - For a list of initial property values for an instance of , see the constructor. + For a list of initial property values for an instance of , see the constructor. @@ -124,10 +124,10 @@ |Property|Initial Value| |--------------|-------------------| -||128| -||`false`| +||128| +||`false`| - You can set the properties to new values before calling or . + You can set the properties to new values before calling or . @@ -261,7 +261,7 @@ ## Examples - The following code example demonstrates setting the value of this property using a constructor, and then displaying the value. + The following code example demonstrates setting the value of this property using a constructor, and then displaying the value. :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/Ping/Overview/asyncping.cs" id="Snippet3"::: @@ -323,7 +323,7 @@ ## Examples - The following code example demonstrates setting the value of this property using a constructor, and then displaying the value. + The following code example demonstrates setting the value of this property using a constructor, and then displaying the value. :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/Ping/Overview/asyncping.cs" id="Snippet3"::: diff --git a/xml/System.Net.NetworkInformation/PingReply.xml b/xml/System.Net.NetworkInformation/PingReply.xml index 6622cc934c4..74397065471 100644 --- a/xml/System.Net.NetworkInformation/PingReply.xml +++ b/xml/System.Net.NetworkInformation/PingReply.xml @@ -57,9 +57,9 @@ ## Remarks The class attempts to send an Internet Control Message Protocol (ICMP) echo request to a remote computer and receive information back from the computer via an ICMP echo reply message. The class uses instances of the class to return information about the operation, such as its status and the time taken to send the request and receive the reply. - The methods return instances of the class directly. The methods return a in the method's parameter. The is accessed through the property. + The methods return instances of the class directly. The methods return a in the method's parameter. The is accessed through the property. - If the value of is not , you should not use the values returned by the , or properties. The property will return zero, the property will return an empty array, and the property will return `null`. + If the value of is not , you should not use the values returned by the , or properties. The property will return zero, the property will return an empty array, and the property will return `null`. @@ -122,7 +122,7 @@ returned by any of the overloads can originate from a malicious remote computer. Do not connect to the remote computer using this address. Use DNS to determine the IP address of the machine to which you want to connect. + The returned by any of the overloads can originate from a malicious remote computer. Do not connect to the remote computer using this address. Use DNS to determine the IP address of the machine to which you want to connect. @@ -184,9 +184,9 @@ option, can be used to discover the maximum transmission unit for the network path between the source and destination computers. For additional information, see "Traceroute" in RFC 1574, Section 3.2, available at [https://www.ietf.org](https://www.ietf.org). + The data buffer sent with the ICMP echo request is returned to the sender in the echo reply so the roundtrip travel time for a packet of a known size can be computed. The data buffer, combined with the option, can be used to discover the maximum transmission unit for the network path between the source and destination computers. For additional information, see "Traceroute" in RFC 1574, Section 3.2, available at [https://www.ietf.org](https://www.ietf.org). - The default buffer used with and contains 32 bytes of data. + The default buffer used with and contains 32 bytes of data. @@ -251,7 +251,7 @@ ## Remarks The TTL defines the number of times nodes can forward a packet as it travels between its source and destination. If the number of forwards, also known as hops, exceeds the value specified for the TTL, the packet is deemed undeliverable and is discarded. - The value specified in the ICMP echo request controls packet fragmentation. If is `true` and the packet size exceeds the maximum transmission unit of the network path taken by the packet, the packet is discarded and the error is returned. + The value specified in the ICMP echo request controls packet fragmentation. If is `true` and the packet size exceeds the maximum transmission unit of the network path taken by the packet, the packet is discarded and the error is returned. @@ -313,7 +313,7 @@ time is reported as 0, which is also a valid value when the request succeeds. You must check the to determine whether the value returned by this property should be ignored. + If the Echo request fails, the time is reported as 0, which is also a valid value when the request succeeds. You must check the to determine whether the value returned by this property should be ignored. @@ -375,7 +375,7 @@ is not , you should not use the values returned by the , or properties. The and properties will return zero, and the property will return `null`. + If the value of is not , you should not use the values returned by the , or properties. The and properties will return zero, and the property will return `null`. diff --git a/xml/System.Net.NetworkInformation/TcpConnectionInformation.xml b/xml/System.Net.NetworkInformation/TcpConnectionInformation.xml index 2766943660b..d0851df2a6b 100644 --- a/xml/System.Net.NetworkInformation/TcpConnectionInformation.xml +++ b/xml/System.Net.NetworkInformation/TcpConnectionInformation.xml @@ -61,7 +61,7 @@ ## Examples The following example displays endpoint information for active TCP connections. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.vb" id="Snippet1"::: @@ -215,7 +215,7 @@ of this connection is , the remote endpoint is not established, and has all zeros for its IP address. + If the of this connection is , the remote endpoint is not established, and has all zeros for its IP address. ]]> diff --git a/xml/System.Net.NetworkInformation/TcpStatistics.xml b/xml/System.Net.NetworkInformation/TcpStatistics.xml index e38bad1f619..4babde6488f 100644 --- a/xml/System.Net.NetworkInformation/TcpStatistics.xml +++ b/xml/System.Net.NetworkInformation/TcpStatistics.xml @@ -49,7 +49,7 @@ and methods, to give applications access to TCP traffic information. + Instances of this class are returned by the and methods, to give applications access to TCP traffic information. The information in this class correlates to the management information objects described in [https://www.ietf.org/rfc/rfc2012.txt](https://www.ietf.org/rfc/rfc2012.txt). @@ -57,7 +57,7 @@ ## Examples The following code example displays the TCP statistics for the specified address family. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet2"::: ]]> @@ -547,7 +547,7 @@ value and the value. + TCP starts a retransmission timer when each outbound segment is passed to the network layer (IP). If no acknowledgement is received for the data in the segment before the timer expires, the segment is retransmitted. The timer can be set to any value between the value and the value. @@ -604,7 +604,7 @@ value and the value. + TCP starts a retransmission timer when each outbound segment is passed to the network layer (IP). If no acknowledgement is received for the data in the segment before the timer expires, the segment is retransmitted. The timer The timer can be set to any value between the value and the value. diff --git a/xml/System.Net.NetworkInformation/UdpStatistics.xml b/xml/System.Net.NetworkInformation/UdpStatistics.xml index ef7ffd33450..e75e175f217 100644 --- a/xml/System.Net.NetworkInformation/UdpStatistics.xml +++ b/xml/System.Net.NetworkInformation/UdpStatistics.xml @@ -49,7 +49,7 @@ and methods to give applications access to UDP traffic information. + Instances of this class are returned by the and methods to give applications access to UDP traffic information. The information in this class correlates to the management information objects described in [https://www.ietf.org/rfc/rfc2013.txt](https://www.ietf.org/rfc/rfc2013.txt). diff --git a/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml b/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml index b5236a5aac4..57ac4836916 100644 --- a/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml +++ b/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml @@ -161,7 +161,7 @@ to determine the preferred address. + Use the value returned by this property to determine how long the preferred address remains valid. Whenever possible, applications should use a preferred address. Use to determine the preferred address. ]]> @@ -217,7 +217,7 @@ to determine the preferred address. + Use the value returned by this property to determine whether this address can be used by your application. Whenever possible, applications should use a preferred address. Use to determine the preferred address. ]]> diff --git a/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml index 4d914abbf7e..3e9ad71a185 100644 --- a/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml @@ -408,11 +408,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> @@ -612,11 +612,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net.PeerToPeer.Collaboration/ContactManager.xml b/xml/System.Net.PeerToPeer.Collaboration/ContactManager.xml index d9e29ec203a..0d79f8e7005 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/ContactManager.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/ContactManager.xml @@ -26,7 +26,7 @@ ## Remarks This class has no public constructors, since a reference to it is returned by the class. - Address books that are associated with management include those associated with the host peer and a remote peer. Either computer may collaborate with other peers; when a peer is local to the remote peer but not the host peer, it can be added to the of the host peer. Certain operations on the class, such as and , correlate to the associated operations being performed on the Windows Address book of the remote peer. + Address books that are associated with management include those associated with the host peer and a remote peer. Either computer may collaborate with other peers; when a peer is local to the remote peer but not the host peer, it can be added to the of the host peer. Certain operations on the class, such as and , correlate to the associated operations being performed on the Windows Address book of the remote peer. The host peer has access to this persistent storage for information, which can be associated with the applications in which a peer intends to participate. A can identify itself as a user of a persistent store on a computer. @@ -132,7 +132,7 @@ ## Remarks This method only returns applications published by contacts of the calling peer. - Before this event can be raised, the current user of the remote peer must subscribe to the collaboration events of the remote peer. Subscription is accomplished via the method. + Before this event can be raised, the current user of the remote peer must subscribe to the collaboration events of the remote peer. Subscription is accomplished via the method. This event requires a of . @@ -253,7 +253,7 @@ method has completed. It is also raised if the operation completes in error or is cancelled. + This event is raised when the method has completed. It is also raised if the operation completes in error or is cancelled. This event requires a of . @@ -569,7 +569,7 @@ . + The associated callback provides a reference to the new . This event requires a of . @@ -613,7 +613,7 @@ methods. + Before this event can be raised, the current user of the remote peer must subscribe to the collaboration events of the host peer. Subscription is accomplished via the PeerContact methods. This event requires a of . @@ -657,7 +657,7 @@ method. + Before this event can be raised, the current user of the remote peer must subscribe to the collaboration events of the host peer. Subscription is accomplished via the method. This event requires a of . diff --git a/xml/System.Net.PeerToPeer.Collaboration/Peer.xml b/xml/System.Net.PeerToPeer.Collaboration/Peer.xml index 4604a89ee81..cd74c12887c 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/Peer.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/Peer.xml @@ -38,7 +38,7 @@ ## Remarks The purpose of the abstract class is to provide a common base class definition that can be shared by derived classes, such as and . It cannot be directly constructed, since it is abstract. Developers should use the subclasses `PeerNearMe` or `PeerContact` instead. - Contact, peer, remote peer, , , and are synonymous terms, based on context. + Contact, peer, remote peer, , , and are synonymous terms, based on context. "Calling peer" and "remote peer" are commonly synonymous. Calling peer does not refer to the application calling a given method. @@ -72,7 +72,7 @@ object, subclassed on or . The PeerContact or the PeerNearMe contain unique references to the name of the new peer object. + Returns a type object, subclassed on or . The PeerContact or the PeerNearMe contain unique references to the name of the new peer object. ]]> @@ -171,7 +171,7 @@ properties. Usage scenarios do not involve this class directly, but rather the derived or the classes. + Two peers are considered equal if they have the same endpoint collection, regardless of the values in their properties. Usage scenarios do not involve this class directly, but rather the derived or the classes. ]]> @@ -263,9 +263,9 @@ If the peer collaboration session did not instantiate with a of , this method cannot access objects on the local computer. The same is true of the applications registered into the collaboration session. - The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. If the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. + The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. If the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. - The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. + The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. NOTE: Additional overloads are defined on the class instead of the subclasses and . @@ -313,9 +313,9 @@ ## Remarks This functionality is only exposed on the class. This functionality is not exposed on any other type of peer for security reasons. - The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. When the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. + The collection of peer objects consists of application, data object, and presence information for the peer or endpoint specified by this instance. If no objects are found for the endpoint, a collection of size zero (0) is returned. When the calling peer is subscribed to this endpoint, the cache is automatically updated; otherwise must be called prior to calling this method. - The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. Calling this method requires a of . This state is created when the collaboration session begins. + The caller is not required to be signed into the collaboration infrastructure for this method to complete successfully. A successful call to or one of the methods must have been completed while the caller was signed in previous to calling this method. Calling this method requires a of . This state is created when the collaboration session begins. NOTE: Additional overloads are defined on the class instead of the derived classes and . @@ -601,7 +601,7 @@ ## Remarks Calling this method guarantees the system will cease to wait for a from the peer associated with the InviteAsync request. - Multiple invitations may be outstanding at any given time. If the method is called when an asynchronous operation identified by the `userToken` is not in existence, an exception is thrown. The `userToken` object must be provided since it is used to track a specific asynchronous call. This host application-supplied object is unique for each invite request. + Multiple invitations may be outstanding at any given time. If the method is called when an asynchronous operation identified by the `userToken` is not in existence, an exception is thrown. The `userToken` object must be provided since it is used to track a specific asynchronous call. This host application-supplied object is unique for each invite request. When this method is used, the event can still be raised, but the Cancelled property on the associated object will be set to `true`. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerApplication.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerApplication.xml index 582aba308ac..8798e319e79 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerApplication.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerApplication.xml @@ -33,19 +33,19 @@ Represents an application that is available for use with the Peer Collaboration infrastructure. - defines the set of software applications or components available for use with the network. This network enables infrastructure participants to initiate usage of this application. They may initiate a collaboration session using the application identified by this class. - - After constructing an instance of this class and setting the appropriate properties, this object may be used in collaboration sessions. Its use is accomplished by passing it to the peer collaboration and methods, which will enable or disable it. - - The globally unique and properties of this instance must be set before the application can successfully be registered. - - After registering an application with the Peer Collaboration infrastructure, the registration information persists in the registry. This makes the application available to collaboration applications even after the program which registered the application has exited. - - Changing the properties on an application instance after it has been registered has no effect on the registration. To update the registration, the application must be unregistered and then registered again with the new information. - + defines the set of software applications or components available for use with the network. This network enables infrastructure participants to initiate usage of this application. They may initiate a collaboration session using the application identified by this class. + + After constructing an instance of this class and setting the appropriate properties, this object may be used in collaboration sessions. Its use is accomplished by passing it to the peer collaboration and methods, which will enable or disable it. + + The globally unique and properties of this instance must be set before the application can successfully be registered. + + After registering an application with the Peer Collaboration infrastructure, the registration information persists in the registry. This makes the application available to collaboration applications even after the program which registered the application has exited. + + Changing the properties on an application instance after it has been registered has no effect on the registration. To update the registration, the application must be unregistered and then registered again with the new information. + ]]> @@ -59,11 +59,11 @@ Initializes a new instance. - and properties of this instance must be set before the application can successfully be registered. - + and properties of this instance must be set before the application can successfully be registered. + ]]> @@ -90,11 +90,11 @@ Initializes a new default instance of the type. - and properties of this instance must be set before the application can successfully be registered. - + and properties of this instance must be set before the application can successfully be registered. + ]]> @@ -121,13 +121,13 @@ The serialization destination associated with the . Initializes a new instance of the type with the data required for serialization. - object with a name fully qualified by the object within it. - - The globally unique and properties of this instance must be set before the application can successfully be registered. - + object with a name fully qualified by the object within it. + + The globally unique and properties of this instance must be set before the application can successfully be registered. + ]]> @@ -164,15 +164,15 @@ The scope in which the application will be registered for peer collaboration. Initializes a new instance with the supplied application ID, description, scope, and data elements. - and properties of this instance must be set before the application can successfully be registered. - + and properties of this instance must be set before the application can successfully be registered. + ]]> - - Length of the binary data object cannot be less than one or greater than 16k. - + - Length of the binary data object cannot be less than one or greater than 16k. + - is set to . @@ -208,11 +208,11 @@ This event is raised whenever a is added, updated or deleted by a remote peer on a subscribed endpoint. - in the of the object that was created when the peer collaboration session began. - + in the of the object that was created when the peer collaboration session began. + ]]> The object has been disposed. @@ -265,11 +265,11 @@ Gets or sets data associated with the current instance. Array of data that contain a binary object to associate with the peer application. This is commonly a small image or XML blob. - invitation, but rather allows additional data to be associated with the application on the local peer. - + invitation, but rather allows additional data to be associated with the application on the local peer. + ]]> The size of this binary data object is either less than 0 or greater than 4,096 bytes. @@ -298,11 +298,11 @@ value that describes the application. Unless specified, the default value for this property is . - invitation. However, it is displayed on the user interface when a receives an invitation for the application. - + invitation. However, it is displayed on the user interface when a receives an invitation for the application. + ]]> The object has been disposed. @@ -426,11 +426,11 @@ if the instance provided has matching data; otherwise, . This method also returns if is . - This object has been disposed. @@ -578,11 +578,11 @@ associated with the instance. Unless specified, the default value for this property is . - The object has been disposed. @@ -613,11 +613,11 @@ The object that contains data to be passed to delegates for the event. Raises the event. - @@ -646,11 +646,11 @@ that represents the file path. Unless explicitly specified, the default value for this property is . - values are not allowed. - + values are not allowed. + ]]> The object has been disposed. @@ -717,13 +717,13 @@ When this property value is set, all events not fired as the result of an asynchronous operation will have the associated event handlers called back on the thread that created the specific . Object that implements the interface and is used by instances of this type for event handler synchronization on the thread that created it. - instance. - + instance. + ]]> The calling object has been disposed. @@ -794,11 +794,11 @@ Returns a string that contains the and of the instance. A string that contains the and of the instance, separated by a space. - . - + . + ]]> The object has been disposed. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerApplicationLaunchInfo.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerApplicationLaunchInfo.xml index 876a6062342..14a50173dd4 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerApplicationLaunchInfo.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerApplicationLaunchInfo.xml @@ -17,13 +17,13 @@ Represents the launch information required by a that has initiated in response to a peer collaboration invitation. - and properties in this class to get the information specific to the invitation that initiated the application launch. - - Access to this class requires a of . This state is created when the collaboration session begins. - + and properties in this class to get the information specific to the invitation that initiated the application launch. + + Access to this class requires a of . This state is created when the collaboration session begins. + ]]> @@ -51,13 +51,13 @@ Gets or sets application-defined binary data associated with the invitation. An array of bytes that containing the data associated with the invitation. - cannot be `null`. - + cannot be `null`. + ]]> @@ -85,11 +85,11 @@ Gets or sets a message associated with the response to the invitation. A text message associated with the to the invitation. - @@ -117,11 +117,11 @@ Gets or sets the for which the invitation was sent. The for which the invitation was sent. - @@ -149,11 +149,11 @@ Gets or sets the that sent the invitation. The that sent the invitation. - @@ -181,11 +181,11 @@ Gets or sets the from which the invitation was sent. The from which the invitation was sent. - diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerCollaboration.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerCollaboration.xml index 760d9d52c08..9fc3b5ef004 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerCollaboration.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerCollaboration.xml @@ -30,9 +30,9 @@ - Invite peers to collaboration sessions, including items such as scope and objects which will identify them over the Internet -- Allow peers to and of the collaboration infrastructure, manage lists of contacts, or publish their presence to each other +- Allow peers to and of the collaboration infrastructure, manage lists of contacts, or publish their presence to each other -- Utilize properties and events to coordinate asynchronous application communication, especially for changes in name, presence, application, or other objects. +- Utilize properties and events to coordinate asynchronous application communication, especially for changes in name, presence, application, or other objects. "Link-local cloud", "subnet of the calling peer", and "NearMe scope" are synonymous terms. "Internet scope" and "serverless presence" are synonymous. The site-local has no equivalent in the collaboration namespace. @@ -71,7 +71,7 @@ instance after it is started to determine whether it was started due to a collaboration request from a remote peer. The calling application should inspect the and properties to get further information about the invitation request. + This property is to be used by a collaboration-aware instance after it is started to determine whether it was started due to a collaboration request from a remote peer. The calling application should inspect the and properties to get further information about the invitation request. Access to this property requires a of . This state is created when the collaboration session begins. @@ -169,7 +169,7 @@ method or prior to the use of this method. + The caller required to sign in to the peer collaboration infrastructure via the method or prior to the use of this method. Access to this property requires a of . This state is created when the collaboration session begins. @@ -211,7 +211,7 @@ method prior to the use of this method. + The caller is required to sign-in to the peer collaboration infrastructure via the method prior to the use of this method. Access to this property requires a of . This state is created when the collaboration session begins. @@ -257,7 +257,7 @@ method prior to the use of this method. + The caller is required to sign-in to the Peer Collaboration infrastructure via the method prior to the use of this method. Access to this method requires a of . This state is created when the collaboration session begins. @@ -616,7 +616,7 @@ method prior to calling this method. + The calling peer is required to sign in to the peer collaboration infrastructure with the method prior to calling this method. Access to this method requires a of . This state is created when the collaboration session begins. @@ -669,7 +669,7 @@ method. + This method allows the object to be queried by remote peers participating in the scope in which the object was registered. If the object was previously registered, this method updates its registration. If a registered object falls out of scope, it can be retrieved via the method. The size of the data portion of the must be less than or equal to 16,384 bytes. @@ -819,7 +819,7 @@ ## Remarks This method is not an application-specific operation and signing out may affect other applications that may be currently running. If the user is not already signed into the specified scope calling this method results in a no-op. - When a user signs out of People Near Me, their published information is deleted from the endpoint object set. This includes and , in addition to any identifying objects registered by the calling peer into the collaboration infrastructure. Because this information is deleted, it is no longer available to either remote peers or a peer host for collaboration. From the perspective of the class, other sharing of the same information with trusted contacts is not relevant; use of the class does not affect other objects in which this information was persisted, such as a remote peer object. Likewise, deleting a peer from the does not affect its presence in a collaboration application; other contacts are still able to view its presence and collaborate with it. + When a user signs out of People Near Me, their published information is deleted from the endpoint object set. This includes and , in addition to any identifying objects registered by the calling peer into the collaboration infrastructure. Because this information is deleted, it is no longer available to either remote peers or a peer host for collaboration. From the perspective of the class, other sharing of the same information with trusted contacts is not relevant; use of the class does not affect other objects in which this information was persisted, such as a remote peer object. Likewise, deleting a peer from the does not affect its presence in a collaboration application; other contacts are still able to view its presence and collaborate with it. Calling this method requires a of . This state is created when the collaboration session begins. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerCollaborationPermission.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerCollaborationPermission.xml index 1a547d117f2..fc2e013fa65 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerCollaborationPermission.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerCollaborationPermission.xml @@ -252,7 +252,7 @@ The parameter's version number is not supported. ## Remarks The intersection of two permissions is a permission that describes the set of operations they both describe in common. Only a demand that passes both original permissions will pass the intersection. - The following statements are required to be `true` for all implementations of the method. X and Y represent object references that are not a `null` reference (`Nothing` in Visual Basic). + The following statements are required to be `true` for all implementations of the method. X and Y represent object references that are not a `null` reference (`Nothing` in Visual Basic). - X.Intersect(X) returns a value equal to X. @@ -310,7 +310,7 @@ The parameter's version number is not supported. ## Remarks The current is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, a permission that represents access to "*C:\example.txt*" is a subset of a permission that represents access to "*C:\\*". If this method returns `true`, the current permission represents no more access to the protected resource than does the specified permission. - The following statements are required to be `true` for all implementations of the method. X, Y, and Z represent objects that are not a `null` reference (`Nothing` in Visual Basic). + The following statements are required to be `true` for all implementations of the method. X, Y, and Z represent objects that are not a `null` reference (`Nothing` in Visual Basic). - X.IsSubsetOf(X) returns `true`. @@ -318,7 +318,7 @@ The parameter's version number is not supported. - If X.IsSubsetOf(Y) and Y.IsSubsetOf(Z) both return `true`, X.IsSubsetOf(Z) returns `true`. - If X represents an empty object with a permission state of `None`, and Y represents an `IPermission` object that is a `null` reference (`Nothing` in Visual Basic), X.IsSubsetOf(Y) returns `true`. If Z is also an empty permission, the compound set operation X.Union(Z).IsSubsetOf(Y) also returns `true` because the of two empty permissions is an empty permission. + If X represents an empty object with a permission state of `None`, and Y represents an `IPermission` object that is a `null` reference (`Nothing` in Visual Basic), X.IsSubsetOf(Y) returns `true`. If Z is also an empty permission, the compound set operation X.Union(Z).IsSubsetOf(Y) also returns `true` because the of two empty permissions is an empty permission. ]]> @@ -460,7 +460,7 @@ The parameter's version number is not supported. is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. The following statements are required to be `true` for all implementations of the Union method. X and Y represent objects that are not a `null` reference (`Nothing` in Visual Basic). diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml index 5ddf9c2a992..5cfe652e348 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml @@ -37,7 +37,7 @@ An application invitation from a is both authenticated and encrypted. The UI dialog to accept or reject an invitation from a peer contact also indicates that the inviter is trusted. - Subscribing to a object means a remote peer can see its registered applications, objects and presence information. To subscribe to a , the caller must be signed in to the peer collaboration infrastructure via or signed in via the Windows UI. All other operations do not require sign-in. + Subscribing to a object means a remote peer can see its registered applications, objects and presence information. To subscribe to a , the caller must be signed in to the peer collaboration infrastructure via or signed in via the Windows UI. All other operations do not require sign-in. ]]> @@ -76,7 +76,7 @@ or methods. + An instance of this object can be obtained from the or methods. ]]> @@ -264,7 +264,7 @@ has the same as the current instance, otherwise `false`. This method also returns `false` if passed parameters are `null`. + Returns `true` if the specified has the same as the current instance, otherwise `false`. This method also returns `false` if passed parameters are `null`. ]]> @@ -378,7 +378,7 @@ is in use simultaneously by two different remote peers. + This can be used to determine whether a is in use simultaneously by two different remote peers. Other objects that may be compared with objects include peer host names, relative peer names, and names de-encapsulated from other objects. @@ -420,7 +420,7 @@ . + The string to pass as the parameter should be obtained from . This class is intended to be a lightweight implementation of a simple XML object model for use within the collaboration infrastructure, and not for use as a general XML object model. @@ -479,9 +479,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. This functionality is only exposed on the class. This functionality is not exposed on any other type of peer for security reasons. @@ -529,9 +529,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. This functionality is only exposed on the class. This functionality is not exposed on any other type of peer for security reasons. @@ -580,9 +580,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. This functionality is only exposed on the class. This functionality is not exposed on any other type of peer for security reasons. @@ -638,9 +638,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. This functionality is only exposed on the class. This functionality is not exposed on any other type of peer for security reasons. @@ -722,7 +722,7 @@ method of the base type. + A derived type must call the method of the base type. ]]> @@ -776,9 +776,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. ]]> @@ -832,9 +832,9 @@ associated with the specified the method must be called prior to calling this method. + If the calling peer is not subscribed to the associated with the specified the method must be called prior to calling this method. - While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. + While the caller is not required to sign-in to the collaboration infrastructure for this method to complete successfully, a successful call to or one of the methods must have been completed while the caller was previously signed in. ]]> @@ -1361,7 +1361,7 @@ ## Remarks In many instances, a is not the same as a peer host. A peer host has an instance within the of the remote peer, and the relationship is that they have invited the peer to collaborate. An endpoint has a "Me" instance within its own contact manager and the peer host, but the relationship is not specified. - If the peer host is in the , and the peer contact chooses not to , its can have a value of blocked, rather than deleting its entry from the host Contact Manager. + If the peer host is in the , and the peer contact chooses not to , its can have a value of blocked, rather than deleting its entry from the host Contact Manager. There is a many-to-many relationship between local peers, remote peers, peer hosts, and subscriptions. Subscriptions are per user, rather than per process, per application, or per domain. Consequently, the subscriptions associated with a object are the list of contacts to which it has subscribed and from which it expects updates. Those contacts either have updated their own application, object, and presence information, or they have updated information regarding contacts in the . @@ -1721,7 +1721,7 @@ updates occur asynchronously after the method has succeeded. As a result, it is possible for a to be added to the collection of a before the associated is provided. + updates occur asynchronously after the method has succeeded. As a result, it is possible for a to be added to the collection of a before the associated is provided. To monitor these changes, it is recommended that the user subscribe to the relevant events; for example, . @@ -1801,7 +1801,7 @@ event is raised upon completion of this operation. If collaboration activities are not required to be asynchronous, the method should be used instead. + The event is raised upon completion of this operation. If collaboration activities are not required to be asynchronous, the method should be used instead. Calling this method requires a of . This state is created when the peer collaboration session begins. @@ -1839,7 +1839,7 @@ object should be examined to determine whether the process completed successfully. + When this event is raised, the error property on the object should be examined to determine whether the process completed successfully. Calling this method requires a of . This state is created when the peer collaboration session begins. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerEndPoint.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerEndPoint.xml index f7594776e93..de04a5d75dc 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerEndPoint.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerEndPoint.xml @@ -33,13 +33,13 @@ Represents the location of a , or instance specified with a unique network address configuration by describing the current instance of a or within the Peer-to-Peer Collaboration Infrastructure. - @@ -54,13 +54,13 @@ Generates a new instance of the class. - they wish to contact. - - Utilizing this constructor to generate an explicit instance facilitates the creation of a class instance that can in turn be used to interact with the peer identified by an IP address, using the Peer Collaboration Infrastructure. - + they wish to contact. + + Utilizing this constructor to generate an explicit instance facilitates the creation of a class instance that can in turn be used to interact with the peer identified by an IP address, using the Peer Collaboration Infrastructure. + ]]> @@ -260,11 +260,11 @@ Gets or sets the that contains the IP address associated with the instance. IP address associated with the instance. - value if the instance was obtained from or . - + value if the instance was obtained from or . + ]]> The specified endpoint is not a valid IPv6 endpoint. @@ -448,11 +448,11 @@ representing the display name of the . - value if the instance was obtained from or . - + value if the instance was obtained from or . + ]]> @@ -551,13 +551,13 @@ When this property value is set, all events not fired as the result of an asynchronous operation will have the associated event handlers called back on the thread that created the specific . Object that implements the interface and is used by instances of this type for event handler synchronization on the thread that created it. - instance. - + instance. + ]]> The calling object has been disposed. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml index fe09936c2bb..b8a60e76b54 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml @@ -33,7 +33,7 @@ method to return a collection of nearby peers. + An instance of this class cannot be created directly. Instead, a reference to the peers "near" the calling peer is obtained by using the static method to return a collection of nearby peers. A peer represented by a object is not necessarily in the calling peer's address book. @@ -420,11 +420,11 @@ and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and the cache has been updated. - The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. + The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. ]]> @@ -729,11 +729,11 @@ and methods as well as the property. This method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. This method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and cache has been updated. - The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. + The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. ]]> @@ -772,11 +772,11 @@ and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and cache has been updated. - The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. + The caller is not required to sign in with the method or via a user interface in to complete this operation successfully. ]]> diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerObject.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerObject.xml index bddc12cacf7..ff597370964 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerObject.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerObject.xml @@ -33,17 +33,17 @@ Represents a new instance of the PeerObject class with an auto-generated . - . - - After constructing an instance of this class and setting the appropriate properties this object may be passed to the and methods to enable/disable the publishing of this object for other peers to discover and view. - - After registering an object with the collaboration infrastructure the registration information is not persisted in the registry, resulting in different behavior from instances. The object registration is only valid for the lifetime duration of the application which registered the object. Applications should unregister objects when they are no longer required or prior to application exit. By default, a PeerObject is automatically unregistered if the instance goes out of scope. - - Changing the properties on a PeerObject instance after it has been registered using the registration methods will not update the registration for the PeerObject instance. To effectively update the registration of a specific PeerObject instance, the PeerObject must be deleted and registered again with the new information. - + . + + After constructing an instance of this class and setting the appropriate properties this object may be passed to the and methods to enable/disable the publishing of this object for other peers to discover and view. + + After registering an object with the collaboration infrastructure the registration information is not persisted in the registry, resulting in different behavior from instances. The object registration is only valid for the lifetime duration of the application which registered the object. Applications should unregister objects when they are no longer required or prior to application exit. By default, a PeerObject is automatically unregistered if the instance goes out of scope. + + Changing the properties on a PeerObject instance after it has been registered using the registration methods will not update the registration for the PeerObject instance. To effectively update the registration of a specific PeerObject instance, the PeerObject must be deleted and registered again with the new information. + ]]> @@ -58,11 +58,11 @@ Initializes a new instance of the class. - instance is constructed, the method must be called to publish the object with the Peer Collaboration infrastructure. - + instance is constructed, the method must be called to publish the object with the Peer Collaboration infrastructure. + ]]> @@ -84,11 +84,11 @@ Initializes a new default instance of the class. - instance is constructed, the method must be called to publish the with the Peer Collaboration infrastructure. - + instance is constructed, the method must be called to publish the with the Peer Collaboration infrastructure. + ]]> @@ -143,11 +143,11 @@ Specifies the scope in which the is to be registered. Initializes a new instance with the associated scope and data. - instance is constructed, the method must be called to publish the with the Peer Collaboration infrastructure. - + instance is constructed, the method must be called to publish the with the Peer Collaboration infrastructure. + ]]> One of the arguments provided to this method is not valid. @@ -396,11 +396,11 @@ The destination for the serialization. Populates a with the data required to serialize the specified . - method. - + method. + ]]> @@ -425,8 +425,8 @@ Gets or sets a associated with the instance. - associated with the - + associated with the + . To be added. The instance has been disposed. @@ -461,11 +461,11 @@ Signaled when a instance changes. - method. - + method. + ]]> diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerObjectCollection.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerObjectCollection.xml index 7b7cc75773c..9cd092a0624 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerObjectCollection.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerObjectCollection.xml @@ -26,11 +26,11 @@ Represents a container for elements of a instance. - static method. - + static method. + ]]> @@ -63,11 +63,11 @@ The new value for the element in the specified index. Inserts a new element into the at the specified index or key. - The argument is . @@ -101,11 +101,11 @@ The new value for the element in the specified index. Replaces the element at the specified index. - The argument is . diff --git a/xml/System.Net.PeerToPeer.Collaboration/PresenceChangedEventArgs.xml b/xml/System.Net.PeerToPeer.Collaboration/PresenceChangedEventArgs.xml index 5a88c381961..83ff1cfe4f2 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PresenceChangedEventArgs.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PresenceChangedEventArgs.xml @@ -70,11 +70,11 @@ object associated with the on which the presence information has changed. - specified by is not associated with a , this value is `null`. - + specified by is not associated with a , this value is `null`. + ]]> diff --git a/xml/System.Net.PeerToPeer/Cloud.xml b/xml/System.Net.PeerToPeer/Cloud.xml index 59839b46c62..015194d5072 100644 --- a/xml/System.Net.PeerToPeer/Cloud.xml +++ b/xml/System.Net.PeerToPeer/Cloud.xml @@ -101,7 +101,7 @@ or to occur in all possible link local clouds. + Use of this property causes a or to occur in all possible link local clouds. ]]> @@ -132,7 +132,7 @@ ## Remarks -- This field is used to automatically call or to on all possible clouds. +- This field is used to automatically call or to on all possible clouds. ]]> @@ -255,9 +255,9 @@ methods are the only ways to get new instances of the class. + This method and the methods are the only ways to get new instances of the class. - Clouds are tied very closely to network interfaces. On a multi-homed machine with two network cards attached to different subnets, three clouds will be returned: one for each of the link local addresses per interface, and a single scope . + Clouds are tied very closely to network interfaces. On a multi-homed machine with two network cards attached to different subnets, three clouds will be returned: one for each of the link local addresses per interface, and a single scope . ]]> @@ -297,7 +297,7 @@ If the `cloudName` parameter is `null` or empty, then `null` is returned. - The scope of the cloud, , link-local, or otherwise, is specified in . + The scope of the cloud, , link-local, or otherwise, is specified in . ]]> @@ -449,7 +449,7 @@ scope . + Clouds are tied very closely to network interfaces. On a multi-homed machine with two network cards attached to different subnets, three network scopes are possible: one for each of the link local addresses per interface, and a single scope . ]]> @@ -481,7 +481,7 @@ , and the other is scope. + On a multi-homed machine with two network cards attached to different subnets, two network scopes are possible: one is a link local , and the other is scope. ]]> diff --git a/xml/System.Net.PeerToPeer/CloudCollection.xml b/xml/System.Net.PeerToPeer/CloudCollection.xml index b7642073db6..e727b97dd17 100644 --- a/xml/System.Net.PeerToPeer/CloudCollection.xml +++ b/xml/System.Net.PeerToPeer/CloudCollection.xml @@ -26,13 +26,13 @@ Represents a container for elements. This class cannot be inherited. - class. Only those methods which are overridden are described below. This collection holds instances of the element, which contain peer information for peer-to-peer networking. - - References of this type are returned by the and methods. - + class. Only those methods which are overridden are described below. This collection holds instances of the element, which contain peer information for peer-to-peer networking. + + References of this type are returned by the and methods. + ]]> @@ -88,11 +88,11 @@ The value for the new element at the specified index. Inserts a into the at the specified index. - The provided cannot be . @@ -124,11 +124,11 @@ The new value for the element to be replaced. Replaces the at the specified index. - The provided cannot be . diff --git a/xml/System.Net.PeerToPeer/PeerName.xml b/xml/System.Net.PeerToPeer/PeerName.xml index 1d76c9a2321..1997d84300f 100644 --- a/xml/System.Net.PeerToPeer/PeerName.xml +++ b/xml/System.Net.PeerToPeer/PeerName.xml @@ -140,7 +140,7 @@ ## Remarks This constructor returns an object of type that contains the fully qualified name of the peer. It also specifies whether the peer name is secured or unsecured. - This instance uses the default peer identity for the current user and the specified , in addition to the type of peer name to create with the specified classifier and type. + This instance uses the default peer identity for the current user and the specified , in addition to the type of peer name to create with the specified classifier and type. ]]> @@ -306,7 +306,7 @@ is appended to the existing portion of the . This string is no more than 149 characters long, including the `null` terminator. Specify `null` to return the peer name of the identity. + The is appended to the existing portion of the . This string is no more than 149 characters long, including the `null` terminator. Specify `null` to return the peer name of the identity. ]]> @@ -371,7 +371,7 @@ and components. + Two peer names are considered equal if they contain identical characters in their and components. No normalizations are performed on the strings prior to comparison. All normalization should have been completed while or before constructing the peer name objects. @@ -474,7 +474,7 @@ method. + A derived type must call the base type method. ]]> diff --git a/xml/System.Net.PeerToPeer/PeerNameRecordCollection.xml b/xml/System.Net.PeerToPeer/PeerNameRecordCollection.xml index cde343a7f08..ed52489bb11 100644 --- a/xml/System.Net.PeerToPeer/PeerNameRecordCollection.xml +++ b/xml/System.Net.PeerToPeer/PeerNameRecordCollection.xml @@ -26,15 +26,15 @@ Represents a container for elements. - element, which are used to specify information about a peer within a . -References to a peer name record collection are returned by the and methods. +References to a peer name record collection are returned by the and methods. + - ]]> @@ -61,11 +61,11 @@ References to a peer name record collection are returned by the Initializes a new instance of the class. - . - + . + ]]> @@ -95,11 +95,11 @@ References to a peer name record collection are returned by the The value for the new element at the specified index. Inserts a element into the at the specified index. - The item provided cannot be . @@ -130,11 +130,11 @@ References to a peer name record collection are returned by the The new value for the element to be replaced. Replaces the at the specified index. - The item provided cannot be . diff --git a/xml/System.Net.PeerToPeer/PeerNameRegistration.xml b/xml/System.Net.PeerToPeer/PeerNameRegistration.xml index f57bf494f4b..bdf3949658a 100644 --- a/xml/System.Net.PeerToPeer/PeerNameRegistration.xml +++ b/xml/System.Net.PeerToPeer/PeerNameRegistration.xml @@ -71,7 +71,7 @@ ## Remarks Returns a new default instance of type . It does not perform peer name registration during construction. - After instantiating an object with this constructor, the caller should populate the appropriate fields in the instance prior to calling or . + After instantiating an object with this constructor, the caller should populate the appropriate fields in the instance prior to calling or . ]]> @@ -108,11 +108,11 @@ and are populated. + Calling this constructor creates an instance that will be used to register all source addresses (both IPv6and IPv4) and the provided port for all clouds in which the peer is currently participating. If the object is constructed successfully, the specified and are populated. - If the peer name is secured and was previously registered in a the peer is currently participating in, an is thrown. + If the peer name is secured and was previously registered in a the peer is currently participating in, an is thrown. - This constructor only creates a instance; it does not perform the registration. After instantiating the registration object with this constructor and populating its fields, the application must call to perform the actual registration. + This constructor only creates a instance; it does not perform the registration. After instantiating the registration object with this constructor and populating its fields, the application must call to perform the actual registration. ]]> @@ -178,11 +178,11 @@ . If the object is constructed successfully, the properties are populated with the specified , and . + Calling this constructor creates an instance that will be used to register all source addresses (both IPv6 and IPv4), the provided port, and the specified . If the object is constructed successfully, the properties are populated with the specified , and . - If the cloud parameter is `null`, the name is registered using the shortcut, which initializes default values for the , , and . + If the cloud parameter is `null`, the name is registered using the shortcut, which initializes default values for the , , and . - After instantiation, the method must be called to register the . + After instantiation, the method must be called to register the . ]]> @@ -267,7 +267,7 @@ that can be supplied is 4,096 bytes. + The maximum amount of that can be supplied is 4,096 bytes. ]]> @@ -287,7 +287,7 @@ ## Remarks When a peer leaves a , the cloud no longer requires the object associated with the peer. Whether the registration object is stopped or disposed is dependent upon whether the cloud will reuse the object to register this peer or another peer. If there are any other endpoint(s) within the registration object with which the peer host expected to communicate, registering those endpoints within the cloud must occur before stopping or disposing of this object. - If the cloud expects to register more peers, the method is recommended; when the cloud no longer needs the memory, it should be returned to the operating system via the method. + If the cloud expects to register more peers, the method is recommended; when the cloud no longer needs the memory, it should be returned to the operating system via the method. ]]> @@ -377,7 +377,7 @@ If a registration method is used that automatically selects the addresses to register, there is no method to determine the addresses for which the peer name was registered. That is, the property will not be updated to reflect the addresses selected. - When a peer name is registered for more than one node, each is distinct and the property defined on each registration instance will be different. Also, when a is registered into more than one , each registration is distinct and the collection of endpoints will usually be different for each instance. + When a peer name is registered for more than one node, each is distinct and the property defined on each registration instance will be different. Also, when a is registered into more than one , each registration is distinct and the collection of endpoints will usually be different for each instance. ]]> @@ -494,7 +494,7 @@ method only when no endpoints are specified. + The default port is used by the method only when no endpoints are specified. ]]> @@ -532,13 +532,13 @@ property with all source addresses and the specified in the constructor. The default port is used by this method only when no endpoints are specified. + The method registers the peer name specified in the property with all source addresses and the specified in the constructor. The default port is used by this method only when no endpoints are specified. - If the property is `null`, this method registers the peer name specified in the property using the field, which initializes default values for the , , and . + If the property is `null`, this method registers the peer name specified in the property using the field, which initializes default values for the , , and . - After a object has been started, the method is used to stop it. + After a object has been started, the method is used to stop it. - To update a registration, the method must be used. + To update a registration, the method must be used. @@ -589,7 +589,7 @@ method may be used to restart it. + After the registration process has been stopped, the registration object's state is equal to the state directly after being constructed by the parameterless constructor. In this state, all of its properties are assumed to have no value. The method may be used to restart it. It is possible to have multiple registration objects for the same peer name. In such a case, if the peer name is secured, each instance will represent a registration in a different PNRP cloud. However, if the peer name is not secured, it can be registered in the same cloud multiple times. @@ -715,7 +715,7 @@ , the system chooses individual endpoints and publishes them with the associated peer name into all available clouds. If the port is not specified, auto selection chooses zero as the . + When auto endpoint selection is used (this property is set to `true`) with no endpoint information specified prior to the start of a , the system chooses individual endpoints and publishes them with the associated peer name into all available clouds. If the port is not specified, auto selection chooses zero as the . When set to `false`, auto selection as described above is not performed. This enables the registration process to publish a peer name along with a data blob (as specified by the property). No endpoints are associated with the name. diff --git a/xml/System.Net.PeerToPeer/PeerNameResolver.xml b/xml/System.Net.PeerToPeer/PeerNameResolver.xml index ae4b7147db9..dc5f22822ea 100644 --- a/xml/System.Net.PeerToPeer/PeerNameResolver.xml +++ b/xml/System.Net.PeerToPeer/PeerNameResolver.xml @@ -45,7 +45,7 @@ , the contains all the information for the specified that was published in the cloud(s) that were queried during the operation. + After successfully resolving a , the contains all the information for the specified that was published in the cloud(s) that were queried during the operation. ]]> @@ -135,9 +135,9 @@ method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. + This method associates peer names to clouds. Calling the method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. - For every method, there is an equivalent method. They are identical in the parameters they are passed, except that the ResolveAsync method includes a system token in its parameter list for asynchronous event handling. + For every method, there is an equivalent method. They are identical in the parameters they are passed, except that the ResolveAsync method includes a system token in its parameter list for asynchronous event handling. If the parameter is not supplied, the method uses the shortcut to fill in cloud parameters. If the `maxRecords` parameter is missing, the default value of zero causes an exception to be thrown. @@ -179,9 +179,9 @@ For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. - Calling the method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. + Calling the method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. If the parameter is not supplied, the method uses the shortcut to fill in cloud parameters. @@ -232,7 +232,7 @@ ## Remarks This method associates a peer name to clouds. All clouds are queried for the peer name. For unsecured peer names, the same peer name can be registered by different users in the same , and associated with different endpoints. If the cannot be resolved (for example, the peer name is not published) an is thrown. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. The event will be raised if the resolve operation completes in error or is canceled. @@ -277,9 +277,9 @@ For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. - If the parameter is `null`, the uses the shortcut to fill in the , , and . + If the parameter is `null`, the uses the shortcut to fill in the , , and . The event will be raised if the resolve operation completes in error or is canceled. @@ -328,9 +328,9 @@ ## Remarks For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. If the peer name cannot be resolved, an is thrown. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling. - If the parameter is `null`, the uses the shortcut to fill in the , , and . + If the parameter is `null`, the uses the shortcut to fill in the , , and . The event will be raised if the resolve operation completes in error or is canceled. @@ -352,7 +352,7 @@ method, there is an equivalent method, which is used when asynchronous processing is required. They are identical in the parameters they are passed, except that ResolveAsync includes a system token in its parameter list for event handling. + For every method, there is an equivalent method, which is used when asynchronous processing is required. They are identical in the parameters they are passed, except that ResolveAsync includes a system token in its parameter list for event handling. If a parameter mismatch occurs between the Resolve method and the ResolveAsync method, and the parameter is not supplied, the method uses the shortcut to fill in cloud parameters. @@ -388,15 +388,15 @@ . It raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. + This method asynchronously associates a peer name to clouds. All clouds are queried for the . It raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. If the peer name cannot be resolved, an is thrown. For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. - Calling the method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. + Calling the method is similar to calling the method for each peer name record in the . Note that using the Resolve method on an individual peer name record does not invalidate resolving multiple peer names. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. All asynchronous references to the resolver object are coordinated with a unique identifier token. This `userState` token or message identifier allows an operating system to deliver a message to a single receiving process after the message has been placed on the message queue. @@ -439,9 +439,9 @@ ## Remarks This method asynchronously associates a peer name to clouds. All clouds are queried for the . For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. If the peer name cannot be resolved or is `null`, an is thrown. - This method raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. + This method raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. All asynchronous references to the resolver object are coordinated with a unique identifier token . This `userState` token or message identifier allows an operating system to deliver a message to a single receiving process after the message has been placed on the message queue. @@ -489,13 +489,13 @@ event, which calls back to the method. Or, it raises the event, which calls back to the method. + This method raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. - If the parameter is `null`, the name is resolved using the shortcut, which initializes default values for the , , and properties. + If the parameter is `null`, the name is resolved using the shortcut, which initializes default values for the , , and properties. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. All asynchronous references to the resolver object are coordinated with a unique identifier token. This `userState` token or message identifier allows an operating system to deliver a message to a single receiving process after the message has been placed on the message queue. @@ -546,11 +546,11 @@ ## Remarks For unsecured peer names, the same name can be registered (and associated with different endpoints) by different peers within the same cloud. - This method raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. + This method raises the event, which calls back to the method. Or, it raises the event, which calls back to the method. - If the parameter is `null`, the name is resolved using the shortcut, which initializes default values for the , , and properties. + If the parameter is `null`, the name is resolved using the shortcut, which initializes default values for the , , and properties. - For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. + For every method, there is an equivalent method. Their parameter lists are identical, except that the ResolveAsync method includes a system token for asynchronous event handling, and the Resolve method is intended for synchronous processing. All asynchronous references to the peer resolver object are coordinated with a unique identifier token . This `userState` token or message identifier allows an operating system to deliver a message to a single receiving process after the message has been placed on the message queue. @@ -602,7 +602,7 @@ This method will return immediately, but the operation may or may not immediately cancel. The event arguments returned by the event contains a field that can be polled by clients to determine whether cancellation occurred. - Calling this method ensures the ResolveCompleted event will be signaled as soon as possible with the event argument set to `true`. + Calling this method ensures the ResolveCompleted event will be signaled as soon as possible with the event argument set to `true`. ]]> @@ -634,7 +634,7 @@ ## Remarks The event will be raised once for each endpoint found, and this event will be raised only once when all endpoints have been found. - This event will also be raised if the operation completes in error or is canceled. + This event will also be raised if the operation completes in error or is canceled. ]]> diff --git a/xml/System.Net.PeerToPeer/PeerNameType.xml b/xml/System.Net.PeerToPeer/PeerNameType.xml index 62de61daa5d..715c7ed9ae4 100644 --- a/xml/System.Net.PeerToPeer/PeerNameType.xml +++ b/xml/System.Net.PeerToPeer/PeerNameType.xml @@ -16,17 +16,17 @@ Defines the type of to create. A peer name is either secured or unsecured. A secured peer name provides a proof of ownership of the name. An unsecured peer name has no identity associated. - , in order to prove ownership. The node does not have a relationship to a public key. - - The format of a peer name is: *Authority.Classifier*. The value of depends on whether the name is a secured peer name or an unsecured peer name. The part of the name can be set to any string that contains 15 or fewer Unicode characters, including the `null` terminator. Once the , and security level of a peer have been established, a peer can also be referred to with a relative name or a host name. - - Only the owner, or peer host, can register a secure peer name with the [PNRP Namespace Provider API](/windows/win32/p2psdk/pnrp-namespace-provider-api). Any node can claim ownership to any unsecured . - - **Note** Using a secured does not ensure the overall security of a networking application. Security of the application is implementation-dependent. - + , in order to prove ownership. The node does not have a relationship to a public key. + + The format of a peer name is: *Authority.Classifier*. The value of depends on whether the name is a secured peer name or an unsecured peer name. The part of the name can be set to any string that contains 15 or fewer Unicode characters, including the `null` terminator. Once the , and security level of a peer have been established, a peer can also be referred to with a relative name or a host name. + + Only the owner, or peer host, can register a secure peer name with the [PNRP Namespace Provider API](/windows/win32/p2psdk/pnrp-namespace-provider-api). Any node can claim ownership to any unsecured . + + **Note** Using a secured does not ensure the overall security of a networking application. Security of the application is implementation-dependent. + ]]> diff --git a/xml/System.Net.PeerToPeer/PnrpPermission.xml b/xml/System.Net.PeerToPeer/PnrpPermission.xml index 660781c09c1..ec87d458e5e 100644 --- a/xml/System.Net.PeerToPeer/PnrpPermission.xml +++ b/xml/System.Net.PeerToPeer/PnrpPermission.xml @@ -331,7 +331,7 @@ The following statements are required to be `true` for all implementations of th - If `X.IsSubsetOf(Y)` and `Y.IsSubsetOf(Z)` both return `true`, `X.IsSubsetOf(Z)` returns `true`. -If X represents an empty object with a permission state of *None*, and Y represents an object that is a `null` reference (`Nothing` in Visual Basic), `X.IsSubsetOf(Y)` returns `true`. If Z is also an empty permission, the compound set operation `X.Union(Z).IsSubsetOf(Y)` also returns `true` because the of two empty permissions is an empty permission. +If X represents an empty object with a permission state of *None*, and Y represents an object that is a `null` reference (`Nothing` in Visual Basic), `X.IsSubsetOf(Y)` returns `true`. If Z is also an empty permission, the compound set operation `X.Union(Z).IsSubsetOf(Y)` also returns `true` because the of two empty permissions is an empty permission. ]]> @@ -467,7 +467,7 @@ If X represents an empty object with a permis is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. + The result of a call to is a permission that represents all the operations represented by both the current and the specified permission. Any demand that passes either permission passes their union. The following statements are required to be `true` for all implementations of the Union method. X and Y represent objects that are not a `null` reference (`Nothing` in Visual Basic). diff --git a/xml/System.Net.PeerToPeer/ResolveCompletedEventArgs.xml b/xml/System.Net.PeerToPeer/ResolveCompletedEventArgs.xml index cad5b6d57fc..919e37bf691 100644 --- a/xml/System.Net.PeerToPeer/ResolveCompletedEventArgs.xml +++ b/xml/System.Net.PeerToPeer/ResolveCompletedEventArgs.xml @@ -17,17 +17,17 @@ Used in conjunction with the event, which is signaled when a resolve request for a specific has completed. - object and utilize one of the Resolve methods. For asynchronous processing, use the method. - - When the Resolver has reached the end of the Cloud(s) to query for the , or it has reached the maximum number of record entries for the it is constructing, the event to complete the resolve process is raised, and the associated delegate causes ResolveAsync to complete. The event can also be raised for abnormal completions, which do not return a collection. - - This event is raised only once when all endpoints have been found. - - All references to this instance of the Resolver object are coordinated with a supplied token, which is a unique, developer-determined identifier for this asynchronous resolve request. - + object and utilize one of the Resolve methods. For asynchronous processing, use the method. + + When the Resolver has reached the end of the Cloud(s) to query for the , or it has reached the maximum number of record entries for the it is constructing, the event to complete the resolve process is raised, and the associated delegate causes ResolveAsync to complete. The event can also be raised for abnormal completions, which do not return a collection. + + This event is raised only once when all endpoints have been found. + + All references to this instance of the Resolver object are coordinated with a supplied token, which is a unique, developer-determined identifier for this asynchronous resolve request. + ]]> @@ -87,13 +87,13 @@ Gets the object to resolve. The object to resolve is the one found in response to a operation on a specific . - event argument for which the OnResolveCompleted method is waiting. The change in state awakens the process. - - Unless explicitly specified, the default value for all properties is `null` for reference types and zero (0) for properties of type `int`. If no records were found, `null` is returned. - + event argument for which the OnResolveCompleted method is waiting. The change in state awakens the process. + + Unless explicitly specified, the default value for all properties is `null` for reference types and zero (0) for properties of type `int`. If no records were found, `null` is returned. + ]]> diff --git a/xml/System.Net.Security/AuthenticatedStream.xml b/xml/System.Net.Security/AuthenticatedStream.xml index c98cc01b400..44bda781ff1 100644 --- a/xml/System.Net.Security/AuthenticatedStream.xml +++ b/xml/System.Net.Security/AuthenticatedStream.xml @@ -57,7 +57,7 @@ ## Remarks This abstract class provides methods and properties that are common to authenticated streams. - Authenticated streams can provide authentication, data signing, and encryption services that can help maintain the integrity and confidentiality of data transmitted using the . + Authenticated streams can provide authentication, data signing, and encryption services that can help maintain the integrity and confidentiality of data transmitted using the . The security protocol implemented by a class that derives from together with the security protocols supported on the client and server will determine the security features that are available to an application. The and classes inherit from and implement the Negotiate and Secure Sockets Layer security protocols, respectively. @@ -288,7 +288,7 @@ The following example demonstrates displaying the properties of an authenticated can use this property to access the stream passed to the . + Classes that inherit from can use this property to access the stream passed to the . ]]> diff --git a/xml/System.Net.Security/NegotiateStream.xml b/xml/System.Net.Security/NegotiateStream.xml index 459a7b397ae..fcab6897228 100644 --- a/xml/System.Net.Security/NegotiateStream.xml +++ b/xml/System.Net.Security/NegotiateStream.xml @@ -65,13 +65,13 @@ - Request server authentication. - Encrypt and/or sign data before transmitting it. - Authentication must be performed before transmitting information. Clients request authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block while waiting for the authentication to complete. Servers request authentication using the synchronous or asynchronous methods. The client, and optionally the server, is authenticated using the Negotiate security protocol. The Kerberos protocol is used for authentication if both client and server support it; otherwise NTLM is used. The class performs the authentication using the Security Support Provider Interface (SSPI). + Authentication must be performed before transmitting information. Clients request authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block while waiting for the authentication to complete. Servers request authentication using the synchronous or asynchronous methods. The client, and optionally the server, is authenticated using the Negotiate security protocol. The Kerberos protocol is used for authentication if both client and server support it; otherwise NTLM is used. The class performs the authentication using the Security Support Provider Interface (SSPI). - When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. + When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. If the authentication fails, you will receive an or a . In this case, you can retry the authentication with a different credential. - You send data using the synchronous or asynchronous or methods. You receive data using the synchronous or asynchronous or methods. If security services such as encryption or signing are enabled, these are automatically applied to your data by the . + You send data using the synchronous or asynchronous or methods. You receive data using the synchronous or asynchronous or methods. If security services such as encryption or signing are enabled, these are automatically applied to your data by the . The transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. @@ -102,7 +102,7 @@ The following code example demonstrates the server side of a client-server conne from closing the stream that you supply, use the constructor. + To prevent the from closing the stream that you supply, use the constructor. ]]> @@ -283,9 +283,9 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + The authentication uses the client's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -356,7 +356,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. ]]> @@ -439,7 +439,7 @@ The following example demonstrates calling this constructor. This code example i The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. ]]> @@ -518,7 +518,7 @@ The following example demonstrates calling this constructor. This code example i value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -599,7 +599,7 @@ The following example demonstrates calling this constructor. This code example i value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . @@ -680,9 +680,9 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. + The authentication uses the client's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -750,7 +750,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -830,7 +830,7 @@ The following example demonstrates calling this constructor. This code example i The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -906,7 +906,7 @@ The following example demonstrates calling this constructor. This code example i value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -990,7 +990,7 @@ The following example demonstrates calling this constructor. This code example i value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . @@ -1032,7 +1032,7 @@ The following example demonstrates calling this constructor. This code example i method. + These methods block while the authentication is in progress. To prevent the application from blocking while waiting for the authentication to complete, use the method. ]]> @@ -1080,11 +1080,11 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1142,13 +1142,13 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1219,9 +1219,9 @@ The following example demonstrates calling this constructor. This code example i and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1301,11 +1301,11 @@ The following example demonstrates calling this constructor. This code example i set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1383,9 +1383,9 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1453,11 +1453,11 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1525,7 +1525,7 @@ The following example demonstrates calling this constructor. This code example i and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1608,9 +1608,9 @@ The following example demonstrates calling this constructor. This code example i set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1649,7 +1649,7 @@ The following example demonstrates calling this constructor. This code example i methods. + The overloads of this method do not block while authentication is in progress. To block while waiting for the authentication to complete, use one of the methods. ]]> @@ -1710,11 +1710,11 @@ The following example demonstrates calling this constructor. This code example i . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . The class will construct the SPN used for mutual authentication. + The authentication uses the client's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . The class will construct the SPN used for mutual authentication. - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1810,9 +1810,9 @@ The following example demonstrates calling this method to begin an asynchronous method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1916,9 +1916,9 @@ The following example demonstrates calling this method to begin an asynchronous method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2019,11 +2019,11 @@ The following example demonstrates calling this method to begin an asynchronous value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2125,11 +2125,11 @@ The following example demonstrates calling this method to begin an asynchronous value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2165,7 +2165,7 @@ The following example demonstrates calling this method to begin an asynchronous method. + The overloads of this method do not block while the authentication is in progress. To block while waiting for the authentication to complete, use the method. ]]> @@ -2226,11 +2226,11 @@ The following example demonstrates calling this method to begin an asynchronous . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - To block until the operation completes, use one of the method overloads. + To block until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2299,13 +2299,13 @@ The following example demonstrates calling this method to begin an asynchronous . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . + The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. - To block until the operation completes, use one of the method overloads. + To block until the operation completes, use one of the method overloads. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2396,11 +2396,11 @@ The following example demonstrates calling this method to begin an asynchronous value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2491,13 +2491,13 @@ The following example demonstrates calling this method to begin an asynchronous value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . + Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that, the requested has been granted. You must check the and properties to determine what security services are used by the . - If the `policy` parameter is `null`, then an extended protection policy is used that has set to . + If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use one of the method overloads. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2593,13 +2593,13 @@ The following example demonstrates calling this method to begin an asynchronous ## Remarks If encryption, signing, or encryption and signing are enabled, the read operation reads the data from the underlying stream, checks the integrity of the data, and decrypts it. If no security services such as data encryption or signing are in use, this method starts an asynchronous read operation on the underlying stream. - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use the method. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use the method. - The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) The class does not support multiple simultaneous read operations. If you attempt to start a read operation while another read operation is already executing on the same stream, a exception will be thrown. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. ## Examples @@ -2702,13 +2702,13 @@ The following example demonstrates calling this method to begin an asynchronous ## Remarks If encryption, signing, or encryption and signing are enabled, this method reads the data from buffer, encrypts, signs, or encrypts and signs it, and transmits it using the underlying stream. If no security services such as data encryption or signing are in use, this method starts an asynchronous write operation on the underlying stream. - This method is asynchronous and does not block while the operation completes. To block until the operation completes, use the method. + This method is asynchronous and does not block while the operation completes. To block until the operation completes, use the method. - The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) + The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. ## Examples @@ -3124,11 +3124,11 @@ The following code example demonstrates displaying the value of this property. and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - To perform this operation synchronously, use one of the method. + To perform this operation synchronously, use one of the method. ]]> @@ -3188,11 +3188,11 @@ The following code example demonstrates displaying the value of this property. ## Remarks If the operation has not completed, this method blocks until it does. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. ]]> @@ -3253,13 +3253,13 @@ The following code example demonstrates displaying the value of this property. ## Remarks If the operation has not completed, this method blocks until it does. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. ## Examples -The following code example demonstrates ending an asynchronous read operation. For an example that demonstrates starting the operation, see . +The following code example demonstrates ending an asynchronous read operation. For an example that demonstrates starting the operation, see . [!code-csharp[NclNegoAsyncServer#3](~/snippets/csharp/System.Net.Security/NegotiateStream/Overview/server.cs#3)] @@ -3323,13 +3323,13 @@ Authentication has not occurred. ## Remarks If the operation has not completed, this method blocks until it does. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. ## Examples -The following example demonstrates a method that is called to complete the asynchronous write operation. For an example that demonstrates starting the operation, see . +The following example demonstrates a method that is called to complete the asynchronous write operation. For an example that demonstrates starting the operation, see . [!code-csharp[NclNegoAsyncClient#4](~/snippets/csharp/System.Net.Security/AuthenticatedStream/Overview/client.cs#4)] [!code-vb[NclNegoAsyncClient#4](~/snippets/visualbasic/System.Net.Security/AuthenticatedStream/Overview/client.vb#4)] @@ -3390,7 +3390,7 @@ Authentication has not occurred. on the underlying stream. + This method invokes on the underlying stream. ## Examples @@ -3441,7 +3441,7 @@ The following code example demonstrates flushing the stream. on the underlying stream. + This method invokes on the underlying stream. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3493,7 +3493,7 @@ The following code example demonstrates flushing the stream. or methods. If you authenticate without specifying a , is used. + You must successfully authenticate before calling this method. Clients specify the impersonation level when they request authentication by calling one of the or methods. If you authenticate without specifying a , is used. ## Examples @@ -3550,7 +3550,7 @@ The following code example demonstrates displaying the value of this property. or methods. Servers authenticate by calling the or methods. + Clients authenticate by calling the or methods. Servers authenticate by calling the or methods. ## Examples @@ -3723,7 +3723,7 @@ The following code example demonstrates displaying the value of this property. ## Remarks If authentication failed or did not occur, this property returns `false`. - To authenticate as the server, call the or methods. + To authenticate as the server, call the or methods. ## Examples @@ -3956,9 +3956,9 @@ The following code example demonstrates displaying the value of this property. ## Remarks The method reads a maximum of `count` bytes from the current stream and stores them in `buffer` beginning at `offset`. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. - To perform this operation asynchronously, use the method. + To perform this operation asynchronously, use the method. ## Examples @@ -4011,7 +4011,7 @@ The following code example demonstrates reading from a , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. ]]> @@ -4063,7 +4063,7 @@ This method reads asynchronously as much data as is available into `buffer` and ## Remarks The method reads asynchronously a maximum of `count` bytes from the current stream and stores them in `buffer` beginning at `offset`. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -4118,9 +4118,9 @@ This method reads asynchronously as much data as is available into `buffer` and property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. + This property returns the value returned by invoking the property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. - If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not time out. + If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not time out. @@ -4341,11 +4341,11 @@ The following code example demonstrates displaying the value of this property. on the underlying stream. + If encryption, signing, or encryption and signing are enabled, this method reads the data from buffer, encrypts, signs, or encrypts and signs it, and transmits it using the underlying stream. If no security services such as data encryption or signing are in use, this method invokes on the underlying stream. - This method blocks while the write operation completes. To prevent blocking while the operation completes, use the method. + This method blocks while the write operation completes. To prevent blocking while the operation completes, use the method. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. The class does not support multiple simultaneous write operations. If you attempt to start a write operation while another write operation is already executing on the same stream, a exception will be thrown. @@ -4415,9 +4415,9 @@ The following code example demonstrates writing to a on the underlying stream. + If encryption, signing, or encryption and signing are enabled, this method reads the data from buffer, encrypts, signs, or encrypts and signs it, and transmits it using the underlying stream. If no security services such as data encryption or signing are in use, this method invokes on the underlying stream. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. ]]> @@ -4467,9 +4467,9 @@ The following code example demonstrates writing to a on the underlying stream. + If encryption, signing, or encryption and signing are enabled, this method reads the data from buffer, encrypts, signs, or encrypts and signs it, and transmits it using the underlying stream. If no security services such as data encryption or signing are in use, this method invokes on the underlying stream. - You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. + You cannot call this method until you have successfully authenticated. To authenticate, call one of the , , , , , or methods. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -4540,9 +4540,9 @@ The following code example demonstrates writing to a property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. + This property returns the value returned by invoking the property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. - If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not time out. + If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not time out. ## Examples diff --git a/xml/System.Net.Security/SslClientAuthenticationOptions.xml b/xml/System.Net.Security/SslClientAuthenticationOptions.xml index 7c768da9966..0f2b002f44a 100644 --- a/xml/System.Net.Security/SslClientAuthenticationOptions.xml +++ b/xml/System.Net.Security/SslClientAuthenticationOptions.xml @@ -46,7 +46,7 @@ and, in .NET 5 and later versions, for . + This property bag is used as argument for and, in .NET 5 and later versions, for . The uses this property bag in the property. diff --git a/xml/System.Net.Security/SslServerAuthenticationOptions.xml b/xml/System.Net.Security/SslServerAuthenticationOptions.xml index f0999473b1e..e321b3680c8 100644 --- a/xml/System.Net.Security/SslServerAuthenticationOptions.xml +++ b/xml/System.Net.Security/SslServerAuthenticationOptions.xml @@ -46,7 +46,11 @@ , or . +======= This property bag is used as argument for , or . +>>>>>>> d00cdce3811a6bba08bd2b4929db3dd9ca0576a2 ]]> @@ -595,7 +599,11 @@ When this property isn't `null`, certain properties on `SslServerAuthenticationO callback. If the delegate is not provided server uses provided as argument of (for the .NET Framework compatibility). If none/neither of those callback are provided, the server falls back to . +======= During the server connection establishment, the server first uses callback. If the delegate is not provided server uses provided as argument of (for the .NET Framework compatibility). If none/neither of those callback are provided, the server falls back to . +>>>>>>> d00cdce3811a6bba08bd2b4929db3dd9ca0576a2 ]]> diff --git a/xml/System.Net.Security/SslStream.xml b/xml/System.Net.Security/SslStream.xml index 7fd56f0dd3e..91f188a1d1d 100644 --- a/xml/System.Net.Security/SslStream.xml +++ b/xml/System.Net.Security/SslStream.xml @@ -58,9 +58,9 @@ ## Remarks SSL protocols help to provide confidentiality and integrity checking for messages transmitted using an . An SSL connection, such as that provided by , should be used when communicating sensitive information between a client and a server. Using an helps to prevent anyone from reading and tampering with information while it is in transit on the network. - An instance transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. Typically, the class is used with the and classes. The method provides a suitable for use with the class. + An instance transmits data using a stream that you supply when creating the . When you supply this underlying stream, you have the option to specify whether closing the also closes the underlying stream. Typically, the class is used with the and classes. The method provides a suitable for use with the class. - After creating an , the server and optionally, the client must be authenticated. The server must provide an X509 certificate that establishes proof of its identity and can request that the client also do so. Authentication must be performed before transmitting information using an . Clients initiate authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block waiting for the authentication to complete. Servers initiate authentication using the synchronous or asynchronous methods. Both client and server must initiate the authentication. + After creating an , the server and optionally, the client must be authenticated. The server must provide an X509 certificate that establishes proof of its identity and can request that the client also do so. Authentication must be performed before transmitting information using an . Clients initiate authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block waiting for the authentication to complete. Servers initiate authentication using the synchronous or asynchronous methods. Both client and server must initiate the authentication. The authentication is handled by the Security Support Provider (SSPI) channel provider. The client is given an opportunity to control validation of the server's certificate by specifying a delegate when creating an . The server can also control validation by supplying a delegate. The method referenced by the delegate includes the remote party's certificate and any errors SSPI encountered while validating the certificate. Note that if the server specifies a delegate, the delegate's method is invoked regardless of whether the server requested client authentication. If the server did not request client authentication, the server's delegate method receives a null certificate and an empty array of certificate errors. @@ -68,7 +68,7 @@ If the authentication fails, you receive a , and the is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - When the authentication process, also known as the SSL handshake, succeeds, the identity of the server (and optionally, the client) is established and the can be used by the client and server to exchange messages. Before sending or receiving information, the client and server should check the security services and levels provided by the to determine whether the protocol, algorithms, and strengths selected meet their requirements for integrity and confidentiality. If the current settings are not sufficient, the stream should be closed. You can check the security services provided by the using the and properties. The following table shows the elements that report the cryptographic settings used for authentication, encryption and data signing. + When the authentication process, also known as the SSL handshake, succeeds, the identity of the server (and optionally, the client) is established and the can be used by the client and server to exchange messages. Before sending or receiving information, the client and server should check the security services and levels provided by the to determine whether the protocol, algorithms, and strengths selected meet their requirements for integrity and confidentiality. If the current settings are not sufficient, the stream should be closed. You can check the security services provided by the using the and properties. The following table shows the elements that report the cryptographic settings used for authentication, encryption and data signing. |Element|Members| |-------------|-------------| @@ -76,16 +76,16 @@ |The key exchange algorithm.|The property and the associated enumeration.| |The message integrity algorithm.|The property and the associated enumeration.| |The message confidentiality algorithm.|The property and the associated enumeration.| -|The strengths of the selected algorithms.|The , , and properties.| +|The strengths of the selected algorithms.|The , , and properties.| - After a successful authentication, you can send data using the synchronous or asynchronous methods. You can receive data using the synchronous or asynchronous methods. + After a successful authentication, you can send data using the synchronous or asynchronous methods. You can receive data using the synchronous or asynchronous methods. - If you specified to the that the underlying stream should be left open, you are responsible for closing that stream when you are done using it. + If you specified to the that the underlying stream should be left open, you are responsible for closing that stream when you are done using it. > [!NOTE] > If the application that creates the object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. - assumes that a timeout along with any other when one is thrown from the inner stream will be treated as fatal by its caller. Reusing a instance after a timeout will return garbage. An application should the and throw an exception in these cases. + assumes that a timeout along with any other when one is thrown from the inner stream will be treated as fatal by its caller. Reusing a instance after a timeout will return garbage. An application should the and throw an exception in these cases. The .NET Framework 4.6 includes a security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, and SslStream and targeting .NET Framework 4.6 get the more-secure behavior by default. @@ -127,7 +127,7 @@ from closing the stream that you supply, use the constructor. + To prevent the from closing the stream that you supply, use the constructor. ]]> @@ -611,7 +611,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -679,7 +679,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -756,7 +756,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -828,7 +828,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -897,7 +897,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -963,7 +963,7 @@ ## Remarks - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1044,7 +1044,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1130,7 +1130,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1200,7 +1200,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] The certificate revocation list is not checked during authentication. The client is not required to provide a certificate for authentication. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1275,7 +1275,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] The certificate revocation list is not checked during authentication. The client is not required to provide a certificate for authentication. - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1345,7 +1345,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1420,7 +1420,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. + This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1816,7 +1816,7 @@ methods. + The overloads of this method do not block while authentication is in progress. To block while waiting for the authentication to complete, use one of the methods. ]]> @@ -1891,9 +1891,9 @@ The value specified for `targetHost` must match the name on the server's certificate. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -1985,9 +1985,9 @@ The value specified for `targetHost` must match the name on the server's certificate. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -2087,9 +2087,9 @@ The value specified for `targetHost` must match the name on the server's certificate. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -2129,7 +2129,7 @@ methods. + The overloads of this method do not block while authentication is in progress. To block while waiting for the authentication to complete, use one of the methods. ]]> @@ -2208,9 +2208,9 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] The certificate revocation list is not checked during authentication. The client is not required to provide a certificate for authentication. - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -2302,9 +2302,9 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -2401,9 +2401,9 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous authentication operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block while the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -2498,15 +2498,15 @@ method. Typically, the method is invoked by the `asyncCallback` delegate. + If encryption and or signing are enabled, the read operation reads the data from the underlying stream, checks the integrity of the data, and/or decrypts it. The asynchronous read operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block while the operation completes. To block until the operation completes, use the method. + This method does not block while the operation completes. To block until the operation completes, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) The class does not support multiple simultaneous read operations. - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. @@ -2686,7 +2686,7 @@ on the underlying stream. + If successful authentication has occurred, this property returns the value returned by invoking on the underlying stream. The underlying stream is specified when you create an instance of the class. @@ -2799,7 +2799,7 @@ on the underlying stream. + This property returns the value returned by invoking on the underlying stream. The underlying stream is specified when you create an instance of the class. @@ -2859,7 +2859,7 @@ on the underlying stream. + If successful authentication has occurred, this property returns the value returned by invoking on the underlying stream. The underlying stream is specified when you create an instance of the class. @@ -3230,11 +3230,11 @@ and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - To perform this operation synchronously, use one of the methods. + To perform this operation synchronously, use one of the methods. ]]> @@ -3291,11 +3291,11 @@ and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. - To perform this operation synchronously, use one of the method. + To perform this operation synchronously, use one of the method. ]]> @@ -3355,9 +3355,9 @@ ## Remarks If the operation has not completed, this method blocks until it does. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. @@ -3428,9 +3428,9 @@ Authentication has not occurred. ## Remarks If the operation has not completed, this method blocks until it does. - An application cannot call this method until you have successfully authenticated. To authenticate, call one of the , or , , methods. + An application cannot call this method until you have successfully authenticated. To authenticate, call one of the , or , , methods. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. @@ -3484,7 +3484,7 @@ Authentication has not occurred. . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information about using the Finalize method, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v%3dvs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -3535,7 +3535,7 @@ Authentication has not occurred. on the underlying stream. + This method invokes on the underlying stream. @@ -3588,7 +3588,7 @@ Authentication has not occurred. on the underlying stream. + This method invokes on the underlying stream. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3768,7 +3768,7 @@ Authentication has not occurred. or methods. Servers authenticate by calling the or methods. + Clients authenticate by calling the or methods. Servers authenticate by calling the or methods. @@ -3946,7 +3946,7 @@ Authentication has not occurred. ## Remarks If authentication failed or did not occur, this property returns `false`. - To authenticate as the server, call the or methods. + To authenticate as the server, call the or methods. @@ -4199,7 +4199,7 @@ Authentication has not occurred. on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + This property returns the value returned by invoking on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. ]]> @@ -4386,7 +4386,7 @@ Authentication has not occurred. ## Remarks -This property gets the cipher suite that is going to be used in the communication between a client and server by the underlying SSL/TLS implementation. It is only available after a successful call to or . +This property gets the cipher suite that is going to be used in the communication between a client and server by the underlying SSL/TLS implementation. It is only available after a successful call to or . ]]> @@ -4436,7 +4436,7 @@ This property gets the cipher suite that is going to be used in the communicatio on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + This property returns the value returned by invoking on the underlying stream. If the underlying stream is not seekable, this method typically throws an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. ]]> @@ -4530,9 +4530,9 @@ This property gets the cipher suite that is going to be used in the communicatio ## Remarks The method reads a maximum of `count` bytes from the stream and stores them in `buffer` beginning at `offset`. You cannot perform multiple simultaneous read operations. - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. - To perform this operation asynchronously, use the method. + To perform this operation asynchronously, use the method. @@ -4779,9 +4779,9 @@ This property gets the cipher suite that is going to be used in the communicatio on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. + This property returns the value returned by invoking on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. - If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not timeout. + If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not timeout. @@ -4958,7 +4958,7 @@ If the property is accessed, the remote certificate will not be disposed when th on the underlying stream specified when this was created. + This method invokes on the underlying stream specified when this was created. ]]> @@ -5046,7 +5046,7 @@ If the property is accessed, the remote certificate will not be disposed when th or via and or . If no security protocol was explicitly specified, the value is used. + The enabled security protocols can be specified in or via and or . If no security protocol was explicitly specified, the value is used. The actual protocol used for authentication is selected based on the ones supported by the client and server. @@ -5191,9 +5191,9 @@ If the property is accessed, the remote certificate will not be disposed when th method. + This method blocks while the operation completes. To prevent blocking while the operation completes, use the method. - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. The class does not support multiple simultaneous write operations. @@ -5294,9 +5294,9 @@ If the property is accessed, the remote certificate will not be disposed when th method. + This method blocks while the operation completes. To prevent blocking while the operation completes the operation completes, use the method. - You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. + You cannot call this method until you have successfully authenticated. To authenticate call one of the , or , , methods. The class does not support multiple simultaneous write operations. @@ -5515,9 +5515,9 @@ The class does not support multiple simulta on the underlying stream. For set operations, the specified value sets the value on the underlying stream. + This property returns the value returned by invoking on the underlying stream. For set operations, the specified value sets the value on the underlying stream. - If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not timeout. + If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not timeout. diff --git a/xml/System.Net.Sockets/IOControlCode.xml b/xml/System.Net.Sockets/IOControlCode.xml index cbbca1b23bd..5020db57d48 100644 --- a/xml/System.Net.Sockets/IOControlCode.xml +++ b/xml/System.Net.Sockets/IOControlCode.xml @@ -47,13 +47,10 @@ enumeration provides named values for specifying socket operational modes. These values are the control codes passed to the Windows Sockets 2 (Winsock 2) `WSAIoctl` function. - - +The enumeration provides named values for specifying socket operational modes. These values are the control codes passed to the Windows Sockets 2 (Winsock 2) `WSAIoctl` function. ## Examples - The following code example calls the method with a DataToRead parameter value and compares the result with accessing the. property. + The following code example calls the method with a DataToRead parameter value and compares the result with accessing the. property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IOControlCode/Overview/iocontrolcode.cs" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/IPPacketInformation.xml b/xml/System.Net.Sockets/IPPacketInformation.xml index 69ce32da2dc..931d7193305 100644 --- a/xml/System.Net.Sockets/IPPacketInformation.xml +++ b/xml/System.Net.Sockets/IPPacketInformation.xml @@ -240,11 +240,11 @@ Returns the hash code for this instance. An Int32 hash code. - and properties. - + and properties. + ]]> @@ -344,11 +344,11 @@ if and are equal; otherwise, . - and values for both arguments. - + and values for both arguments. + The equivalent method for this operator is .]]> @@ -400,11 +400,11 @@ if and are unequal; otherwise, . - and values for both arguments. - + and values for both arguments. + The equivalent method for this operator is .]]> diff --git a/xml/System.Net.Sockets/LingerOption.xml b/xml/System.Net.Sockets/LingerOption.xml index cb0b36abc5b..34cc1f7dde3 100644 --- a/xml/System.Net.Sockets/LingerOption.xml +++ b/xml/System.Net.Sockets/LingerOption.xml @@ -50,14 +50,14 @@ or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. + There may still be data available in the outgoing network buffer after an application calls the or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a when the property is not set and for a when the property is not set. ## Examples - The following example sets a previously created to linger one second after calling the method. + The following example sets a previously created to linger one second after calling the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/Overview/source.vb" id="Snippet1"::: @@ -115,7 +115,7 @@ ## Remarks There may still be data available in the outgoing network buffer after you close the . Use the `enable` parameter to specify whether you would like the to continue transmitting unsent data after the close method is called. Use the `seconds` parameter to indicate how long you would like the to attempt transferring unsent data before timing out. If you specify `true` for the `enable` parameter and 0 for the `seconds` parameter, the will attempt to send data until there is no data left in the outgoing network buffer. If you specify `false` for the `enable` parameter, the will close immediately and any unsent data will be lost. - The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. + The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. |`enable`|`seconds`|Behavior| |--------------|---------------|--------------| @@ -130,7 +130,7 @@ ## Examples - The following example sets a previously created to linger one second after calling the method. + The following example sets a previously created to linger one second after calling the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/Overview/source.vb" id="Snippet1"::: @@ -194,7 +194,7 @@ property to determine whether the will linger after closing. Change this value to `true` or `false` and pass the altered to the method or set the or property.to disable or enable lingering. + You can use the property to determine whether the will linger after closing. Change this value to `true` or `false` and pass the altered to the method or set the or property.to disable or enable lingering. The following table describes the behavior for the possible values of the property and the property stored in the property. @@ -328,7 +328,7 @@ ## Remarks Use this value if you want to determine how long a closed will attempt to transfer unsent data before timing out. You can also set this value to the desired time-out period, in seconds. - If the property is `true`, and you set to 0, the discards any pending data to send in the outgoing network buffer. If you change this value, you must pass the altered instance to the method or set the or property. + If the property is `true`, and you set to 0, the discards any pending data to send in the outgoing network buffer. If you change this value, you must pass the altered instance to the method or set the or property. The following table describes the behavior for the possible values of the property and the property stored in the property. diff --git a/xml/System.Net.Sockets/MulticastOption.xml b/xml/System.Net.Sockets/MulticastOption.xml index 45685d999cb..b134a1c03a1 100644 --- a/xml/System.Net.Sockets/MulticastOption.xml +++ b/xml/System.Net.Sockets/MulticastOption.xml @@ -56,7 +56,7 @@ to store the of a multicast group you want to join or drop. Use the method with the following parameters to join a multicast group. + Use a to store the of a multicast group you want to join or drop. Use the method with the following parameters to join a multicast group. |Parameter|Value| |---------------|-----------| @@ -420,7 +420,7 @@ property contains the IP address of the interface associated with the multicast group membership. If is set to , the default interface is used. + The property contains the IP address of the interface associated with the multicast group membership. If is set to , the default interface is used. ## Examples The following example displays the value of this property. diff --git a/xml/System.Net.Sockets/NetworkStream.xml b/xml/System.Net.Sockets/NetworkStream.xml index 186a0b08f34..38c999c3caa 100644 --- a/xml/System.Net.Sockets/NetworkStream.xml +++ b/xml/System.Net.Sockets/NetworkStream.xml @@ -66,9 +66,9 @@ To create a , you must provide a connected . You can also specify what permission the has over the provided . By default, closing the does not close the provided . If you want the to have permission to close the provided , you must specify `true` for the value of the `ownsSocket` parameter. - Use the and methods for simple single threaded synchronous blocking I/O. If you want to process your I/O asynchronously, consider using the or -based methods and . + Use the and methods for simple single threaded synchronous blocking I/O. If you want to process your I/O asynchronously, consider using the or -based methods and . - The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . + The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. @@ -133,7 +133,7 @@ ## Remarks The is created with read/write access to the specified . - The does not own the underlying , so calling the or method does not close the . + The does not own the underlying , so calling the or method does not close the . ]]> @@ -199,7 +199,7 @@ ## Remarks The is created with read/write access to the specified . - If the value of `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . + If the value of `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . ]]> @@ -262,9 +262,9 @@ ## Remarks The is created with the specified access to the specified . - With this constructor, the does not own the underlying , so calling the or method does not close the underlying . + With this constructor, the does not own the underlying , so calling the or method does not close the underlying . - The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. + The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. ]]> @@ -334,9 +334,9 @@ ## Remarks The is created with read/write access to the specified . - If the value of the `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . + If the value of the `ownsSocket` parameter is `true`, the takes ownership of the underlying , and calling the or method also closes the underlying . - The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. + The `access` parameter sets the and properties of the . If you specify , then the allows calls to the method. If you specify , then the allows calls to the method. If you specify , both method calls are allowed. ]]> @@ -438,9 +438,9 @@ > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. The operation reads as much data as is available, up to the number of bytes specified by the `count` parameter. @@ -558,9 +558,9 @@ > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. > [!NOTE] > If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. @@ -647,11 +647,11 @@ is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . + If is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . > [!NOTE] > The property is set when the is initialized. -> Changes in the underlying 's state (eg. closure) do not affect the value of . +> Changes in the underlying 's state (eg. closure) do not affect the value of . ]]> @@ -804,11 +804,11 @@ is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . + If is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . > [!NOTE] > The property is set when the is initialized. -> Changes in the underlying 's state (eg. closure) do not affect the value of . +> Changes in the underlying 's state (eg. closure) do not affect the value of . ]]> @@ -915,9 +915,9 @@ myNetworkStream->Close(); method frees both unmanaged and managed resources associated with the . If the owns the underlying , it is closed as well. + The method frees both unmanaged and managed resources associated with the . If the owns the underlying , it is closed as well. - If a was associated with a , the method will close the TCP connection, but not dispose of the associated . + If a was associated with a , the method will close the TCP connection, but not dispose of the associated . ]]> @@ -1014,8 +1014,8 @@ The Close method frees both unmanaged and managed resources associated with the ## Remarks Use the property to determine if data is queued to be immediately read. - If is `true`, a call to returns immediately. - If the remote host shuts down or closes the connection, may throw a . + If is `true`, a call to returns immediately. + If the remote host shuts down or closes the connection, may throw a . > [!NOTE] > Do not use to determine whether the transmission has ended. Even if there's no data available to be immediately read, the underlying socket may receive more data later. @@ -1145,7 +1145,7 @@ The Close method frees both unmanaged and managed resources associated with the > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. + The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] > If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. @@ -1211,7 +1211,7 @@ The Close method frees both unmanaged and managed resources associated with the > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. + The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] > If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. @@ -1276,7 +1276,7 @@ The Close method frees both unmanaged and managed resources associated with the . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information about using the Finalize method, see [Finalize Methods and Destructors](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/0s71x931(v%3dvs.100)), [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged), and [Overriding the Finalize Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -1328,7 +1328,7 @@ The Close method frees both unmanaged and managed resources associated with the method implements the method; however, because is not buffered, it has no effect on network streams. Calling the method does not throw an exception. + The method implements the method; however, because is not buffered, it has no effect on network streams. Calling the method does not throw an exception. ]]> @@ -1691,7 +1691,7 @@ There is a failure reading from the network. class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. + You must derive from the class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. The property is set when the is initialized. @@ -1943,7 +1943,7 @@ There is a failure reading from the network. If the read operation does not complete within the time specified by this property, the read operation throws an . > [!NOTE] -> This property affects only synchronous reads performed by calling the method. This property does not affect asynchronous reads performed by calling the or method. +> This property affects only synchronous reads performed by calling the method. This property does not affect asynchronous reads performed by calling the or method. ## Examples @@ -2287,7 +2287,7 @@ This method starts at the specified `offset` and sends `count` bytes from the co ## Examples - The following code example checks to see whether the is writable. If it is, then is used to write a small message. + The following code example checks to see whether the is writable. If it is, then is used to write a small message. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Overview/source.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/NetworkStream/Write/source.vb" id="Snippet3"::: @@ -2373,7 +2373,7 @@ There was a failure while writing to the network. class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. + You must derive from the class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. The property is set when the is initialized. @@ -2636,7 +2636,7 @@ There was a failure while writing to the network. If the write operation does not complete within the time specified by this property, the write operation throws a . > [!NOTE] -> This property affects only synchronous write operations performed by calling the method. This property does not affect asynchronous writes performed by calling the or method. +> This property affects only synchronous write operations performed by calling the method. This property does not affect asynchronous writes performed by calling the or method. diff --git a/xml/System.Net.Sockets/SelectMode.xml b/xml/System.Net.Sockets/SelectMode.xml index 9396cd4fe12..392178aeb73 100644 --- a/xml/System.Net.Sockets/SelectMode.xml +++ b/xml/System.Net.Sockets/SelectMode.xml @@ -49,13 +49,13 @@ enumeration defines the polling modes that can be passed to the method. Use the SelectRead value to determine if a listening has incoming connection requests. Use the SelectWrite value to determine if a is writeable. Use the SelectError value to determine if there is an error condition present on the . For explanations of writeability, readability, and the presence of error conditions, see the method. + The enumeration defines the polling modes that can be passed to the method. Use the SelectRead value to determine if a listening has incoming connection requests. Use the SelectWrite value to determine if a is writeable. Use the SelectError value to determine if there is an error condition present on the . For explanations of writeability, readability, and the presence of error conditions, see the method. ## Examples - The following example checks the status of a using all three enumeration values. A call to using the SelectWrite enumerated value should return `true`. - + The following example checks the status of a using all three enumeration values. A call to using the SelectWrite enumerated value should return `true`. + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SelectMode/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/SelectMode/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/SendPacketsElement.xml b/xml/System.Net.Sockets/SendPacketsElement.xml index f7e044b10aa..28c96fda690 100644 --- a/xml/System.Net.Sockets/SendPacketsElement.xml +++ b/xml/System.Net.Sockets/SendPacketsElement.xml @@ -55,7 +55,7 @@ class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -117,7 +117,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -160,7 +160,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -200,7 +200,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -255,7 +255,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -299,7 +299,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -358,7 +358,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -409,7 +409,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -471,7 +471,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -522,7 +522,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -587,7 +587,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -640,7 +640,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -704,7 +704,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -757,7 +757,7 @@ class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -880,7 +880,7 @@ ## Remarks The default value for the property is zero if the class was not initialized with a `count` parameter. - If is zero for a file, the entire file is sent. If is zero for a buffer, no bytes are sent. + If is zero for a file, the entire file is sent. If is zero for a buffer, no bytes are sent. ]]> diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 6d4a2e8887e..8c92bc72149 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -208,7 +208,7 @@ This method populates the instance with data ga constructor multiple times with the same byte array as the argument for each call, you will create multiple managed s with the same underlying socket. This practice is strongly discouraged. + If you call the constructor multiple times with the same byte array as the argument for each call, you will create multiple managed s with the same underlying socket. This practice is strongly discouraged. ]]> @@ -400,14 +400,14 @@ This method populates the instance with data ga synchronously extracts the first pending connection request from the connection request queue of the listening socket, and then creates and returns a new . You cannot use this returned to accept any additional connections from the connection queue. However, you can call the method of the returned to identify the remote host's network address and port number. + synchronously extracts the first pending connection request from the connection request queue of the listening socket, and then creates and returns a new . You cannot use this returned to accept any additional connections from the connection queue. However, you can call the method of the returned to identify the remote host's network address and port number. - In blocking mode, blocks until an incoming connection attempt is queued. Once a connection is accepted, the original continues queuing incoming connection requests until you close it. + In blocking mode, blocks until an incoming connection attempt is queued. Once a connection is accepted, the original continues queuing incoming connection requests until you close it. - If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> Before calling the method, you must first call the method to listen for and queue incoming connection requests. +> Before calling the method, you must first call the method to listen for and queue incoming connection requests. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -576,7 +576,7 @@ This method populates the instance with data ga method to asynchronously process incoming connection attempts. Accepting connections asynchronously gives you the ability to send and receive data within a separate execution thread. Before calling the method, you must call the method to listen for and queue incoming connection requests. + Connection-oriented protocols can use the method to asynchronously process incoming connection attempts. Accepting connections asynchronously gives you the ability to send and receive data within a separate execution thread. Before calling the method, you must call the method to listen for and queue incoming connection requests. To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and hook it to the event. @@ -586,15 +586,15 @@ This method populates the instance with data ga The caller can optionally specify an existing to use for the incoming connection by specifying the to use with the property. - If the property is null, a new is constructed with the same , , and as the current and set as the property. + If the property is null, a new is constructed with the same , , and as the current and set as the property. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. + Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. - The completion callback method should examine the property to determine if the operation was successful. + The completion callback method should examine the property to determine if the operation was successful. - The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. + The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. ]]> @@ -837,9 +837,9 @@ This method populates the instance with data ga , is a good way to determine whether data is queued for reading, before calling . The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, returns 0. + If you are using a non-blocking , is a good way to determine whether data is queued for reading, before calling . The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, returns 0. - If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -932,13 +932,13 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. + Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > You can use the property of the returned to identify the remote host's network address and port number. @@ -1039,13 +1039,13 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. + Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > You can use the property of the returned to identify the remote host's network address and port number. @@ -1144,13 +1144,13 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. + Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > You can use the property of the returned to identify the remote host's network address and port number. @@ -1266,13 +1266,13 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. + Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > You can use the property of the returned to identify the remote host's network address and port number. @@ -1376,23 +1376,23 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. + If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . - If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. + If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. > [!NOTE] -> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. +> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1492,23 +1492,23 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. + If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . - If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. + If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. > [!NOTE] -> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. +> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1608,23 +1608,23 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. + If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call and set Broadcast to `true`. If you cannot, will throw a . - If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. + If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the or method. If you want to change the default remote host, call the method again with the desired endpoint. - To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. > [!NOTE] -> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. +> If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1713,11 +1713,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - If you are using a connection-oriented protocol, you can call the method to initiate disconnection from a remote endpoint. If `reuseSocket` is `true`, you can reuse the socket. + If you are using a connection-oriented protocol, you can call the method to initiate disconnection from a remote endpoint. If `reuseSocket` is `true`, you can reuse the socket. - You can pass a callback that implements to in order to get notified about the completion of the disconnect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the disconnect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. > [!NOTE] > If you receive a exception, use the property to obtain the specific error code. @@ -1813,11 +1813,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -1918,11 +1918,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -2033,11 +2033,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -2156,11 +2156,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. + Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -2287,21 +2287,21 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. In these cases, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. + This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. In these cases, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - To guarantee that the remote host endpoint is always returned, an application should explicitly bind the to a local endpoint using the method and then call the method with the `optionLevel` parameter set to or as appropriate, the `optionName` parameter set to , and the `optionValue` parameter to enable this option before calling the method. Otherwise, it is possible for the remote host endpoint to not be returned when the sender has sent a number of datagrams before the receiver has called the method. + To guarantee that the remote host endpoint is always returned, an application should explicitly bind the to a local endpoint using the method and then call the method with the `optionLevel` parameter set to or as appropriate, the `optionName` parameter set to , and the `optionValue` parameter to enable this option before calling the method. Otherwise, it is possible for the remote host endpoint to not be returned when the sender has sent a number of datagrams before the receiver has called the method. - Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the / method or accept an incoming connection request by calling the or method. If you call the method before establishing or accepting a connection, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. + Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the / method or accept an incoming connection request by calling the or method. If you call the method before establishing or accepting a connection, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. The `remoteEp` parameter - With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. + With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. - To cancel a pending , call the method. + To cancel a pending , call the method. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -2424,13 +2424,13 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - To cancel a pending , call the method. + To cancel a pending , call the method. - This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent, as well as information about the received packet. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. + This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent, as well as information about the received packet. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -2549,11 +2549,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. @@ -2659,11 +2659,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. @@ -2779,11 +2779,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. @@ -2905,11 +2905,11 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. @@ -3035,11 +3035,11 @@ This method populates the instance with data ga This overload sends the file `fileName` over the socket. If `fileName` is in the local directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards ("..\\\myfile.txt") and UNC share names ("\\\\\\\shared directory\\\myfile.txt") are supported. If the file is not found, the exception is thrown. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] > If you receive a exception, use the property to obtain the specific error code. @@ -3131,11 +3131,11 @@ This method populates the instance with data ga The `flags` parameter provides additional information about the file transfer. For more information about how to use this parameter, see . - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. + Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] > If you receive a exception, use the property to obtain the specific error code. @@ -3238,15 +3238,15 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. - If you are using a connection-oriented protocol, you must first call the , , , or method, or will throw a . will ignore the `remoteEP` parameter and send data to the established in the , , , or method. + If you are using a connection-oriented protocol, you must first call the , , , or method, or will throw a . will ignore the `remoteEP` parameter and send data to the established in the , , , or method. - If you are using a connectionless protocol, you do not need to establish a default remote host with the or method prior to calling . You only need to do this if you intend to call the method. If you do call the or method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the or method prior to calling . You only need to do this if you intend to call the method. If you do call the or method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - If you want to send data to a broadcast address, you must first call the method and set the socket option to . -You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you want to send data to a broadcast address, you must first call the method and set the socket option to . -You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. @@ -3344,22 +3344,22 @@ This method populates the instance with data ga method if you need to use a specific local endpoint. You must call before you can call the method. You do not need to call before using the method unless you need to use a specific local endpoint. You can use the method on both connectionless and connection-oriented protocols. + Use the method if you need to use a specific local endpoint. You must call before you can call the method. You do not need to call before using the method unless you need to use a specific local endpoint. You can use the method on both connectionless and connection-oriented protocols. - Before calling , you must first create the local from which you intend to communicate data. If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. + Before calling , you must first create the local from which you intend to communicate data. If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. - If you use the above approach, you can discover what local network address and port number has been assigned by calling the . If you are using a connection-oriented protocol, will not return the locally assigned network address until after you have made a call to the or method. If you are using a connectionless protocol, you will not have access to this information until you have completed a send or receive. + If you use the above approach, you can discover what local network address and port number has been assigned by calling the . If you are using a connection-oriented protocol, will not return the locally assigned network address until after you have made a call to the or method. If you are using a connectionless protocol, you will not have access to this information until you have completed a send or receive. - If a UDP socket wants to receive interface information on received packets, the method should be explicitly called with the socket option set to immediately after calling the method. + If a UDP socket wants to receive interface information on received packets, the method should be explicitly called with the socket option set to immediately after calling the method. > [!NOTE] -> If you intend to receive multicast datagrams, you must call the method with a multicast port number. +> If you intend to receive multicast datagrams, you must call the method with a multicast port number. > [!NOTE] -> You must call the method if you intend to receive connectionless datagrams using the method. +> You must call the method if you intend to receive connectionless datagrams using the method. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3505,7 +3505,7 @@ This method populates the instance with data ga method cancels an asynchronous request for a remote host connection. + The method cancels an asynchronous request for a remote host connection. ]]> @@ -3571,14 +3571,14 @@ This method populates the instance with data ga method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. + The method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. - For connection-oriented protocols, it is recommended that you call before calling the method. This ensures that all data is sent and received on the connected socket before it is closed. + For connection-oriented protocols, it is recommended that you call before calling the method. This ensures that all data is sent and received on the connected socket before it is closed. - If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. + If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time out period. Use this along with the socket option to call the method. +> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time out period. Use this along with the socket option to call the method. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3645,14 +3645,14 @@ This method populates the instance with data ga method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. + The method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. - For connection-oriented protocols, it is recommended that you call before calling . This ensures that all data is sent and received on the connected socket before it is closed. + For connection-oriented protocols, it is recommended that you call before calling . This ensures that all data is sent and received on the connected socket before it is closed. - If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. + If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time-out period. Use this along with the socket option to call the method. +> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time-out period. Use this along with the socket option to call the method. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3731,17 +3731,17 @@ This method populates the instance with data ga method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call , you can send data to the remote device with the method, or receive data from the remote device with the method. + If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call , you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] -> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. +> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. > [!NOTE] -> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. +> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3823,17 +3823,17 @@ This method populates the instance with data ga method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. + If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] -> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. +> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. > [!NOTE] -> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. +> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3906,17 +3906,17 @@ This method populates the instance with data ga , which can return multiple IP addresses for a single host. If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. + This method is typically used immediately after a call to , which can return multiple IP addresses for a single host. If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] -> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. +> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. > [!NOTE] -> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. +> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3989,19 +3989,19 @@ This method populates the instance with data ga method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. + If you're using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you're using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you're using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - The method will block, unless you specifically set the property to `false` prior to calling . If you're using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you're using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. - If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. + If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you're using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. +> If you're using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. > [!NOTE] -> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. +> If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4131,31 +4131,31 @@ This method populates the instance with data ga method starts an asynchronous request for a connection to the remote host. If you are using a connectionless protocol, establishes a default remote host. + If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the remote host. If you are using a connectionless protocol, establishes a default remote host. To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. - If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . + If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . The following properties and events on the object are required: - -- +- - Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. - If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. + If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. - If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. + If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. - The method throws if the address family of the and the are not the same address family. + The method throws if the address family of the and the are not the same address family. > [!NOTE] > If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -4554,31 +4554,31 @@ This method populates the instance with data ga establishes a default remote host specified by the `socketType` and `protocolType` parameters. + If you are using a connection-oriented protocol, the M:System.Net.Sockets.Socket.ConnectAsync(System.Net.Sockets.SocketType,System.Net.Sockets.ProtocolType,System.Net.Sockets.SocketAsyncEventArgs) method starts an asynchronous request for a connection to the remote host. If you are using a connectionless protocol, establishes a default remote host specified by the `socketType` and `protocolType` parameters. To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. - If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . + If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . The following properties and events on the object are required: - -- +- - Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. - If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. + If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. - If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. + If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. - The method throws if the address family of the and the are not the same address family. + The method throws if the address family of the and the are not the same address family. > [!NOTE] > If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -4743,7 +4743,7 @@ This method populates the instance with data ga The value of the property reflects the state of the connection as of the most recent operation. If you need to determine the current state of the connection, make a nonblocking, zero-byte Send call. If the call returns successfully or throws a WAEWOULDBLOCK error code (10035), then the socket is still connected; otherwise, the socket is no longer connected. - If you call on a User Datagram Protocol (UDP) socket, the property always returns `true`; however, this action does not change the inherent connectionless nature of UDP. + If you call on a User Datagram Protocol (UDP) socket, the property always returns `true`; however, this action does not change the inherent connectionless nature of UDP. @@ -4808,9 +4808,9 @@ This method populates the instance with data ga ## Remarks If you are using a connection-oriented protocol, you can use this method to close the socket. This method ends the connection and sets the property to `false`. However, if `reuseSocket` is `true`, you can reuse the socket. - To ensure that all data is sent and received before the socket is closed, you should call before calling the method. + To ensure that all data is sent and received before the socket is closed, you should call before calling the method. - If you need to call without first calling , you can set the option to `false` and specify a nonzero time-out interval to ensure that data queued for outgoing transmission is sent. then blocks until the data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. + If you need to call without first calling , you can set the option to `false` and specify a nonzero time-out interval to ensure that data queued for outgoing transmission is sent. then blocks until the data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -4821,7 +4821,7 @@ This method populates the instance with data ga ## Examples - The following code example creates a socket for synchronous communication and sends some data to a remote host. It then calls , to stop the send and receive activity, and , to close the socket connection. + The following code example creates a socket for synchronous communication and sends some data to a remote host. It then calls , to stop the send and receive activity, and , to close the socket connection. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/BeginAccept/nclsocketenhancements.cs" id="Snippet12"::: @@ -4883,7 +4883,7 @@ This method populates the instance with data ga method requests a disconnect from a remote endpoint. If you set to `true` in the `e` parameter, the socket can be reused. + When using a connection-oriented protocol, calling the method requests a disconnect from a remote endpoint. If you set to `true` in the `e` parameter, the socket can be reused. ]]> @@ -5125,7 +5125,7 @@ This method populates the instance with data ga option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. + Datagrams require fragmentation when their size exceeds the Maximum Transfer Unit (MTU) of the transmission medium. Datagrams may be fragmented by the sending host (all Internet Protocol versions) or an intermediate router (Internet Protocol Version 4 only). If a datagram must be fragmented and the option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. Setting this property on a Transmission Control Protocol (TCP) socket has no effect. @@ -5389,9 +5389,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. + The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5472,11 +5472,11 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The `buffer` parameter of this overload contains the data that was received in the call to and the `bytesTransferred` parameter contains the number of bytes that were transferred in the call. + The `buffer` parameter of this overload contains the data that was received in the call to and the `bytesTransferred` parameter contains the number of bytes that were transferred in the call. - The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. + The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5556,9 +5556,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. + The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5634,7 +5634,7 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. + completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5712,7 +5712,7 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. + completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5800,9 +5800,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5888,9 +5888,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -5977,9 +5977,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. To obtain the received data, call the method of the object, and extract the buffer contained in the resulting state object. To identify the originating host, extract the and cast it to an . Use the method to obtain the IP address and the method to obtain the port number. + The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. To obtain the received data, call the method of the object, and extract the buffer contained in the resulting state object. To identify the originating host, extract the and cast it to an . Use the method to obtain the IP address and the method to obtain the port number. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -6061,7 +6061,7 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. + completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. Examine `ipPacketInformation` if you need to know if the datagram was sent using a unicast, multicast, or broadcast address. @@ -6151,11 +6151,11 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until some of the buffer was sent. If the return value from indicates that the buffer was not completely sent, call the method again, modifying the buffer to hold the unsent data. + If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until some of the buffer was sent. If the return value from indicates that the buffer was not completely sent, call the method again, modifying the buffer to hold the unsent data. - There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -6244,11 +6244,11 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until some of the buffer was sent. If the return value from indicates that the buffer was not completely sent, call the method again, modifying the buffer to hold the unsent data. + If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until some of the buffer was sent. If the return value from indicates that the buffer was not completely sent, call the method again, modifying the buffer to hold the unsent data. - There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. @@ -6334,9 +6334,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - If you are using a connectionless protocol, blocks until the datagram is sent. If you are using a connection-oriented protocol, blocks until the entire file is sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connectionless protocol, blocks until the datagram is sent. If you are using a connection-oriented protocol, blocks until the entire file is sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -6414,9 +6414,9 @@ Duplication of the socket reference failed. > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - completes the operation started by . You need to pass the created by the matching call. + completes the operation started by . You need to pass the created by the matching call. - If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until the requested number of bytes are sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until the requested number of bytes are sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -6487,11 +6487,11 @@ Duplication of the socket reference failed. is `false`, multiple sockets can use the method to bind to a specific port; however only one of the sockets can perform operations on the network traffic sent to the port. If more than one socket attempts to use the method to bind to a particular port, then the one with the more specific IP address will handle the network traffic sent to that port. + If is `false`, multiple sockets can use the method to bind to a specific port; however only one of the sockets can perform operations on the network traffic sent to the port. If more than one socket attempts to use the method to bind to a particular port, then the one with the more specific IP address will handle the network traffic sent to that port. - If is `true`, the first use of the method to attempt to bind to a particular port, regardless of Internet Protocol (IP) address, will succeed; all subsequent uses of the method to attempt to bind to that port will fail until the original bound socket is destroyed. + If is `true`, the first use of the method to attempt to bind to a particular port, regardless of Internet Protocol (IP) address, will succeed; all subsequent uses of the method to attempt to bind to that port will fail until the original bound socket is destroyed. - This property must be set before is called; otherwise an will be thrown. + This property must be set before is called; otherwise an will be thrown. ## Examples The following code example demonstrates the use of the property. @@ -6554,7 +6554,7 @@ Duplication of the socket reference failed. class finalizer calls the method to close the and free resources associated with the . + The class finalizer calls the method to close the and free resources associated with the . ]]> @@ -6718,7 +6718,7 @@ In general, the `GetSocketOption` method should be used whenever getting a options determine the behavior of the current . Use this overload to get the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to set the value of any of the options listed above, use the method. + options determine the behavior of the current . Use this overload to get the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to set the value of any of the options listed above, use the method. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -6729,7 +6729,7 @@ In general, the `GetSocketOption` method should be used whenever getting a and time-out values and displays them to the console. + The following code example retrieves the and time-out values and displays them to the console. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet2"::: @@ -6803,7 +6803,7 @@ In general, the `GetSocketOption` method should be used whenever getting a options determine the behavior of the current . Upon successful completion of this method, the array specified by the `optionValue` parameter contains the value of the specified option. - When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. + When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6811,7 +6811,7 @@ In general, the `GetSocketOption` method should be used whenever getting a and time-out values and displays them to the console. + The following code example retrieves the and time-out values and displays them to the console. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet2"::: @@ -6884,7 +6884,7 @@ In general, the `GetSocketOption` method should be used whenever getting a will throw a . Use this overload for any sockets that are represented by Boolean values or integers. + The `optionLength` parameter sets the maximum size of the returned byte array. If the option value requires fewer bytes, the array will contain only that many bytes. If the option value requires more bytes, will throw a . Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -6895,7 +6895,7 @@ In general, the `GetSocketOption` method should be used whenever getting a and time-out values and displays them to the console. + The following code example retrieves the and time-out values and displays them to the console. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet2"::: @@ -7024,7 +7024,7 @@ In general, the `GetSocketOption` method should be used whenever getting a method provides low-level access to the operating system underlying the current instance of the class. For more information, see the [WSAIoctl](/windows/win32/api/winsock2/nf-winsock2-wsaioctl) documentation. + The method provides low-level access to the operating system underlying the current instance of the class. For more information, see the [WSAIoctl](/windows/win32/api/winsock2/nf-winsock2-wsaioctl) documentation. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -7113,7 +7113,7 @@ In general, the `GetSocketOption` method should be used whenever getting a with and the property. + The following code example compares the results of calling with and the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IOControlCode/Overview/iocontrolcode.cs" id="Snippet1"::: @@ -7171,7 +7171,7 @@ In general, the `GetSocketOption` method should be used whenever getting a method, or implicitly bound by calling members like , , or , which use an ephemeral local port (a free port greater than 1024, selected by the operating system.) Servers use the method to bind to a well-known port so that clients may connect to them. + A socket is considered bound to a local port if it is explicitly bound by calling the method, or implicitly bound by calling members like , , or , which use an ephemeral local port (a free port greater than 1024, selected by the operating system.) Servers use the method to bind to a well-known port so that clients may connect to them. @@ -7241,15 +7241,15 @@ In general, the `GetSocketOption` method should be used whenever getting a property changes the way method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. + The property changes the way method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. - This property controls the length of time that a connection-oriented connection will remain open after a call to when data remains to be sent. + This property controls the length of time that a connection-oriented connection will remain open after a call to when data remains to be sent. - When you call methods to send data to a peer, this data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the method drops the connection. + When you call methods to send data to a peer, this data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the method drops the connection. To enable lingering, create a instance containing the desired values, and set the property to this instance. - The following table describes the behavior of the method for the possible values of the property and the property stored in the property. + The following table describes the behavior of the method for the possible values of the property and the property stored in the property. |LingerState.Enabled|LingerState.LingerTime|Behavior| |-------------------------|----------------------------|--------------| @@ -7369,12 +7369,12 @@ The maximum length of the pending connections queue is determined automatically. causes a connection-oriented to listen for incoming connection attempts. The `backlog` parameter specifies the number of incoming connections that can be queued for acceptance. To determine the maximum number of connections you can specify, retrieve the value. does not block. + causes a connection-oriented to listen for incoming connection attempts. The `backlog` parameter specifies the number of incoming connections that can be queued for acceptance. To determine the maximum number of connections you can specify, retrieve the value. does not block. - If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use or to accept a connection from the queue. + If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use or to accept a connection from the queue. > [!NOTE] -> You must call the method before calling , or will throw a . +> You must call the method before calling , or will throw a . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7454,9 +7454,9 @@ The maximum length of the pending connections queue is determined automatically. property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. + The property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. - The property is usually set after you make a call to the method. If you allow the system to assign your socket's local IP address and port number, the property will be set after the first I/O operation. For connection-oriented protocols, the first I/O operation would be a call to the or method. For connectionless protocols, the first I/O operation would be any of the send or receive calls. + The property is usually set after you make a call to the method. If you allow the system to assign your socket's local IP address and port number, the property will be set after the first I/O operation. For connection-oriented protocols, the first I/O operation would be a call to the or method. For connectionless protocols, the first I/O operation would be any of the send or receive calls. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -7811,7 +7811,7 @@ The maximum length of the pending connections queue is determined automatically. method checks the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses or data becomes available. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. + The method checks the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses or data becomes available. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -7823,7 +7823,7 @@ The maximum length of the pending connections queue is determined automatically. > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example creates a socket, connects to a server, and uses to check the status of the socket. + The following code example creates a socket, connects to a server, and uses to check the status of the socket. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SelectMode/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/SelectMode/Overview/source.vb" id="Snippet1"::: @@ -8011,17 +8011,17 @@ The maximum length of the pending connections queue is determined automatically. method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. + The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer. The buffer offset defaults to 0, the size defaults to the length of the buffer parameter, and the value defaults to . - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8118,13 +8118,13 @@ The maximum length of the pending connections queue is determined automatically. This overload requires you to provide one or more receive buffers. - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8184,17 +8184,17 @@ The maximum length of the pending connections queue is determined automatically. ## Remarks -The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. +The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer. The buffer offset defaults to 0, the size defaults to the length of the buffer parameter, and the value defaults to . -If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection before calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. +If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection before calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. -If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. +If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. -If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. +If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8265,17 +8265,17 @@ This member outputs trace information when you enable network tracing in your ap method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. + The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer and the necessary . The buffer offset defaults to 0, and the size defaults to the length of the byte parameter. - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. - If you are using a connection-oriented , the method will read as much data as is available up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8368,13 +8368,13 @@ This member outputs trace information when you enable network tracing in your ap This overload requires you to provide one or more receive buffers. The value defaults to . - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8453,17 +8453,17 @@ This member outputs trace information when you enable network tracing in your ap method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. +The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer. The buffer offset defaults to 0, the size defaults to the length of the buffer parameter, and the value defaults to . -If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. +If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. -If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. +If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. -If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. +If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8543,17 +8543,17 @@ This member outputs trace information when you enable network tracing in your ap method reads data into the `buffer` parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. + The method reads data into the `buffer` parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer, the number of bytes you want to receive, and the necessary . - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8650,13 +8650,13 @@ This member outputs trace information when you enable network tracing in your ap This overload requires you to provide one or more receive buffers. The value defaults to . - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8730,17 +8730,17 @@ This member outputs trace information when you enable network tracing in your ap method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. +The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. This overload only requires you to provide a receive buffer. The buffer offset defaults to 0, the size defaults to the length of the buffer parameter, and the value defaults to . -If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. +If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. -If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. +If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. -If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. +If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8817,15 +8817,15 @@ If you're using a connectionless , method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. + The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -8936,15 +8936,15 @@ If you're using a connectionless , method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. + The method reads data into the buffer parameter and returns the number of bytes successfully read. You can call from both connection-oriented and connectionless sockets. - If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. + If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. - If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. + If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9124,7 +9124,7 @@ If you're using a connectionless , method is used on connected sockets or bound connectionless sockets and is used to read incoming data. The socket's local address must be known. + The method is used on connected sockets or bound connectionless sockets and is used to read incoming data. The socket's local address must be known. For bound connectionless sockets, this function restricts the addresses from which received messages are accepted. The function only returns messages from the remote address specified in the connection. Messages from other addresses are silently discarded. @@ -9132,21 +9132,21 @@ If you're using a connectionless , object are required to successfully call this method: -- or +- or -- if is set +- if is set -- if is set +- if is set - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer associated with the `e` parameter. If the message is larger than the buffer, the buffer is filled with the first part of the message. - For connection-oriented sockets, the method can indicate the graceful termination of the virtual circuit in one of two ways that depend on whether the socket is byte stream or message oriented. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a with the set to the native Winsock WSAEDISCON error code (10101) is used to indicate graceful closure. In any case, a with the set to the native Winsock WSAECONNRESET error code (10054) indicates an abortive close has occurred. + For connection-oriented sockets, the method can indicate the graceful termination of the virtual circuit in one of two ways that depend on whether the socket is byte stream or message oriented. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a with the set to the native Winsock WSAEDISCON error code (10101) is used to indicate graceful closure. In any case, a with the set to the native Winsock WSAECONNRESET error code (10054) indicates an abortive close has occurred. ]]> @@ -9478,26 +9478,26 @@ If you're using a connectionless , method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. + The method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. This overload only requires you to provide a receive `buffer`, and an that represents the remote host. The buffer offset defaults to 0. The size defaults to the length of the `buffer` parameter and the `socketFlags` value defaults to . > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . - With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. + With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. + Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. - With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> The of the used in needs to match the of the used in . +> The of the used in needs to match the of the used in . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9635,26 +9635,26 @@ If you're using a connectionless , method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. + The method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. This overload only requires you to provide a receive buffer, the necessary , and an that represents the remote host. The offset defaults to 0 and the size defaults to the length of the buffer parameter. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . - With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. + With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. + Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. - With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. + With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> The of the used in needs to match the of the used in . +> The of the used in needs to match the of the used in . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9662,7 +9662,7 @@ If you're using a connectionless , are passed to the method. + The following code example receives a connectionless datagram from a remote host. are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet10"::: @@ -9855,23 +9855,23 @@ If you're using a connectionless , method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. + The method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. This overload only requires you to provide a receive buffer, the number of bytes you want to receive, the necessary , and an that represents the remote host. The buffer offset defaults to 0. - With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. + With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. + Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. - With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. + With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> The of the used in needs to match the of the used in . +> The of the used in needs to match the of the used in . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9879,7 +9879,7 @@ If you're using a connectionless , are passed to the method. + The following code example receives a connectionless datagram from a remote host. The buffer size, and are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet11"::: @@ -9977,21 +9977,21 @@ If you're using a connectionless , method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. + The method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent. This method is useful if you intend to receive connectionless datagrams from an unknown host or multiple hosts. - With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. + With connectionless protocols, will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. - Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. + Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. - With connection-oriented sockets, will read as much data as is available up to the amount of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. + With connection-oriented sockets, will read as much data as is available up to the amount of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> The of the used in needs to match the of the used in . +> The of the used in needs to match the of the used in . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9999,7 +9999,7 @@ If you're using a connectionless , are passed to the method. + The following code example receives a connectionless datagram from a remote host. The offset, buffer size, and are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet12"::: @@ -10099,7 +10099,7 @@ If you're using a connectionless , method is used primarily to receive data on a connectionless socket. The socket's local address must be known. + The method is used primarily to receive data on a connectionless socket. The socket's local address must be known. The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. @@ -10107,21 +10107,21 @@ If you're using a connectionless , object are required to successfully call this method: -- +- -- +- -- +- -- +- - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. + For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. - For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. The and properties determine where in the buffer the data is placed and the amount of data. + For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. The and properties determine where in the buffer the data is placed and the amount of data. ]]> @@ -10527,20 +10527,20 @@ You must call the Bind method before performing this operation. method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent, as well as information about the received packet. + The method reads data into the `buffer` parameter, returns the number of bytes successfully read, and captures the remote host endpoint from which the data was sent, as well as information about the received packet. - The method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . + The method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . - For message-oriented sockets, an incoming message is placed into the `buffer` parameter up to the total size specified in the `size` parameter. The `offset` parameter determines where in the `buffer` the data is placed. The actual amount of data placed into the `buffer` is returned by the method. + For message-oriented sockets, an incoming message is placed into the `buffer` parameter up to the total size specified in the `size` parameter. The `offset` parameter determines where in the `buffer` the data is placed. The actual amount of data placed into the `buffer` is returned by the method. - The method automatically method sets the socket option to `true` the first time it is called for a given . However, the returned object will only be valid for packets which arrive at the local computer after the socket option has been set. If a socket is sent packets between when it is bound to a local endpoint (explicitly by the method or implicitly by one of the , , , or methods) and its first call to the method, calls to method will return invalid objects for these packets. + The method automatically method sets the socket option to `true` the first time it is called for a given . However, the returned object will only be valid for packets which arrive at the local computer after the socket option has been set. If a socket is sent packets between when it is bound to a local endpoint (explicitly by the method or implicitly by one of the , , , or methods) and its first call to the method, calls to method will return invalid objects for these packets. - To ensure that all objects are valid, an application should set the socket option to `true` before it is bound to a local endpoint using the method. + To ensure that all objects are valid, an application should set the socket option to `true` before it is bound to a local endpoint using the method. An application can examine the `ipPacketInformation` parameter if it needs to know if the datagram was sent using a unicast, multicast, or broadcast address. > [!NOTE] -> The of the used in needs to match the of the used in . +> The of the used in needs to match the of the used in . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -10642,29 +10642,29 @@ You must call the Bind method before performing this operation. method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . + The method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. The following properties and events on the object are required to successfully call this method: -- +- -- +- -- +- -- +- - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. + For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. - The method automatically sets the socket option to `true` the first time it is called for a given . However, the object will only be valid for packets which arrive at the local computer after the socket option has been set. If a socket is sent packets between when the socket is bound to a local endpoint (explicitly by the method or implicitly by one of the , , , or methods) and the first call to the method, calls to method will result in invalid objects for these packets. + The method automatically sets the socket option to `true` the first time it is called for a given . However, the object will only be valid for packets which arrive at the local computer after the socket option has been set. If a socket is sent packets between when the socket is bound to a local endpoint (explicitly by the method or implicitly by one of the , , , or methods) and the first call to the method, calls to method will result in invalid objects for these packets. - To ensure that all objects are valid, an application should set the socket option to`true` before it is bound to a local endpoint using the method. + To ensure that all objects are valid, an application should set the socket option to`true` before it is bound to a local endpoint using the method. An application can examine the resulting objects if it needs to know if the datagram was sent using a unicast, multicast, or broadcast address. @@ -10942,7 +10942,7 @@ You must call the Bind method before performing this operation. calls only. If the time-out period is exceeded, the method will throw a . + This option applies to synchronous calls only. If the time-out period is exceeded, the method will throw a . @@ -11013,9 +11013,9 @@ You must call the Bind method before performing this operation. property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. + If you are using a connection-oriented protocol, the property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. - The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -11139,18 +11139,18 @@ You must call the Bind method before performing this operation. is a static method that determines the status of one or more instances. You must place one or more sockets into an before you can use the method. Check for readability by calling with the as the `checkRead` parameter. To check your sockets for writability, use the `checkWrite` parameter. For detecting error conditions, use `checkError`. After calling , the will be filled with only those sockets that satisfy the conditions. + is a static method that determines the status of one or more instances. You must place one or more sockets into an before you can use the method. Check for readability by calling with the as the `checkRead` parameter. To check your sockets for writability, use the `checkWrite` parameter. For detecting error conditions, use `checkError`. After calling , the will be filled with only those sockets that satisfy the conditions. - If you are in a listening state, readability means that a call to will succeed without blocking. If you have already accepted the connection, readability means that data is available for reading. In these cases, all receive operations will succeed without blocking. Readability can also indicate whether the remote has shut down the connection; in that case a call to will return immediately, with zero bytes returned. + If you are in a listening state, readability means that a call to will succeed without blocking. If you have already accepted the connection, readability means that data is available for reading. In these cases, all receive operations will succeed without blocking. Readability can also indicate whether the remote has shut down the connection; in that case a call to will return immediately, with zero bytes returned. - returns when at least one of the sockets of interest (the sockets in the `checkRead`, `checkWrite`, and `checkError` lists) meets its specified criteria, or the `microSeconds` parameter is exceeded, whichever comes first. Setting `microSeconds` to -1 specifies an infinite time-out. + returns when at least one of the sockets of interest (the sockets in the `checkRead`, `checkWrite`, and `checkError` lists) meets its specified criteria, or the `microSeconds` parameter is exceeded, whichever comes first. Setting `microSeconds` to -1 specifies an infinite time-out. - If you make a nonblocking call to , writability means that you have connected successfully. If you already have a connection established, writability means that all send operations will succeed without blocking. + If you make a nonblocking call to , writability means that you have connected successfully. If you already have a connection established, writability means that all send operations will succeed without blocking. - If you have made a non-blocking call to , the `checkerror` parameter identifies sockets that have not connected successfully. + If you have made a non-blocking call to , the `checkerror` parameter identifies sockets that have not connected successfully. > [!NOTE] -> Use the method if you only want to determine the status of a single . +> Use the method if you only want to determine the status of a single . > [!NOTE] > This method cannot detect certain kinds of connection problems, such as a broken network cable, or that the remote host was shut down ungracefully. You must attempt to send or receive data to detect these kinds of errors. @@ -11161,7 +11161,7 @@ You must call the Bind method before performing this operation. ## Examples - The following code example uses to determine which listening sockets have a connection request. + The following code example uses to determine which listening sockets have a connection request. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Select/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Select/source.vb" id="Snippet1"::: @@ -11287,15 +11287,15 @@ You must call the Bind method before performing this operation. synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. This overload requires a buffer that contains the data you want to send. The value defaults to 0, the buffer offset defaults to 0, and the number of bytes to send defaults to the size of the buffer. - If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11389,15 +11389,15 @@ You must call the Bind method before performing this operation. can be used for both connection-oriented and connectionless protocols. + can be used for both connection-oriented and connectionless protocols. This overload requires at least one buffer that contains the data you want to send. - If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11464,15 +11464,15 @@ You must call the Bind method before performing this operation. ## Remarks - synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. This overload requires a buffer that contains the data you want to send. The value defaults to 0, the buffer offset defaults to 0, and the number of bytes to send defaults to the size of the buffer. -If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. +If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. -If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don't use the method, you'll have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host before calling by making another call to . +If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don't use the method, you'll have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host before calling by making another call to . -If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. +If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] >If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11545,18 +11545,18 @@ This member outputs trace information when you enable network tracing in your ap synchronously sends data to the remote host established in the or method and returns the number of bytes successfully sent. The method can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host established in the or method and returns the number of bytes successfully sent. The method can be used for both connection-oriented and connectionless protocols. This overload requires a buffer that contains the data you want to send and a bitwise combination of . The buffer offset defaults to 0, and the number of bytes to send defaults to the size of the buffer. If you specify the flag as the `socketflags` parameter value, the data you are sending will not be routed. - If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call the method before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call the method before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11645,11 +11645,11 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks This overload requires at least one buffer that contains the data you want to send. The value defaults to 0. If you specify the flag as the `socketFlags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11789,18 +11789,18 @@ This member outputs trace information when you enable network tracing in your ap synchronously sends data to the remote host established in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host established in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. This overload requires a buffer that contains the data you want to send, the number of bytes you want to send, and a bitwise combination of any . If you specify the flag as the `socketflags` parameter, the data you're sending won't be routed. -If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. +If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. -If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don'tuse the method, you'll have to call the method before each call to the method. You can use even after you've established a default remote host with . You can also change the default remote host before calling by making another call to . +If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don'tuse the method, you'll have to call the method before each call to the method. You can use even after you've established a default remote host with . You can also change the default remote host before calling by making another call to . -With a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. +With a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram won't be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram won't be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -11896,11 +11896,11 @@ The following code example sends the data found in buffer, and specifies value defaults to 0. If you specify the flag as the `socketFlags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11970,15 +11970,15 @@ The following code example sends the data found in buffer, and specifies synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. This overload requires a buffer that contains the data you want to send. The value defaults to 0, the buffer offset defaults to 0, and the number of bytes to send defaults to the size of the buffer. -If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. +If you're using a connectionless protocol, you must call before calling this method, or will throw a . If you're using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. -If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don't use the method, you'll have to call before each call to . You can use even after you've established a default remote host with . You can also change the default remote host before calling by making another call to . +If you're using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you don't use the method, you'll have to call before each call to . You can use even after you've established a default remote host with . You can also change the default remote host before calling by making another call to . -If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. +If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] >If you receive a , use the property to obtain the specific error code. After you've obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -12055,17 +12055,17 @@ This member outputs trace information when you enable network tracing in your ap synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. In this overload, if you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you must call before calling this method or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use . If you do not use , you will have to call before each call to . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use . If you do not use , you will have to call before each call to . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -12173,17 +12173,17 @@ This member outputs trace information when you enable network tracing in your ap synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. + synchronously sends data to the remote host specified in the or method and returns the number of bytes successfully sent. can be used for both connection-oriented and connectionless protocols. In this overload, if you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you must call before calling this method or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method or will throw a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connectionless protocol and plan to send data to several different hosts, you should use . If you do not use , you will have to call before each call to . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . + If you are using a connectionless protocol and plan to send data to several different hosts, you should use . If you do not use , you will have to call before each call to . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -12382,29 +12382,29 @@ This member outputs trace information when you enable network tracing in your ap method is used to write outgoing data from one or more buffers on a connection-oriented socket. This method can also be used, however, on connectionless sockets that have specified a remote host on a connect operation. + The method is used to write outgoing data from one or more buffers on a connection-oriented socket. This method can also be used, however, on connectionless sockets that have specified a remote host on a connect operation. - The method starts an asynchronous send operation to the remote host established in the , , , , , or method. + The method starts an asynchronous send operation to the remote host established in the , , , , , or method. The following properties and events on the object are required to successfully call this method: -- or +- or -- if is set +- if is set -- if is set +- if is set - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - The method will throw an exception if you do not first call , , , , or . + The method will throw an exception if you do not first call , , , , or . - Calling the method gives you the ability to send data within a separate execution thread. + Calling the method gives you the ability to send data within a separate execution thread. - For message-oriented sockets, do not exceed the maximum message size of the underlying Windows sockets service provider. If the data is too long to pass atomically through the underlying service provider, no data is transmitted and the method throws a with the set to the native Winsock WSAEMSGSIZE error code (10040). + For message-oriented sockets, do not exceed the maximum message size of the underlying Windows sockets service provider. If the data is too long to pass atomically through the underlying service provider, no data is transmitted and the method throws a with the set to the native Winsock WSAEMSGSIZE error code (10040). - Note that the successful completion of the method does not indicate that the data was successfully delivered. + Note that the successful completion of the method does not indicate that the data was successfully delivered. ]]> @@ -12733,11 +12733,11 @@ This member outputs trace information when you enable network tracing in your ap This method uses the `TransmitFile` function found in the Windows Sockets 2 API. For more information about the `TransmitFile` function and its flags, see the [Windows Sockets](/windows/desktop/WinSock/) documentation. - synchronously sends a file to the remote host specified in the or method. can be used for both connection-oriented and for connectionless protocols. + synchronously sends a file to the remote host specified in the or method. can be used for both connection-oriented and for connectionless protocols. - If you are using a connectionless protocol, you must call before calling this method, otherwise throws a exception. If you are using a connection-oriented protocol, you must either use to establish a remote host connection or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method, otherwise throws a exception. If you are using a connection-oriented protocol, you must either use to establish a remote host connection or use to accept an incoming connection. - If you are using a connection-oriented protocol, blocks until the file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, blocks until the file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -12820,11 +12820,11 @@ This member outputs trace information when you enable network tracing in your ap This method uses the `TransmitFile` function found in the Windows Sockets 2 API. For more information about the `TransmitFile` function and its flags, see the [Windows Sockets](/windows/desktop/WinSock/) documentation. - synchronously sends a file to the remote host specified in the or method. can be used for both connection-oriented and for connectionless protocols. + synchronously sends a file to the remote host specified in the or method. can be used for both connection-oriented and for connectionless protocols. - If you are using a connectionless protocol, you must call before calling this method; otherwise throws a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. + If you are using a connectionless protocol, you must call before calling this method; otherwise throws a . If you are using a connection-oriented protocol, you must either use to establish a remote host connection, or use to accept an incoming connection. - If you are using a connection-oriented protocol, blocks until the entire file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, blocks until the entire file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -13062,7 +13062,7 @@ This member outputs trace information when you enable network tracing in your ap method is used to send a collection of files or in memory data buffers to remote host. The must already be connected to the remote host. + The method is used to send a collection of files or in memory data buffers to remote host. The must already be connected to the remote host. If a references a file in the working directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards and UNC share names are supported. If the file is not found, is thrown. @@ -13072,21 +13072,21 @@ This member outputs trace information when you enable network tracing in your ap The following properties and events on the object are required to successfully call this method: -- +- - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. This method uses the TransmitPackets function found in the Windows Sockets 2 API. For more information about the TransmitPackets function and its flags, see the [Windows Sockets](/windows/desktop/WinSock/) documentation. - Although intended for connection-oriented protocols, the method also works for connectionless protocols, provided that you first call the , , or method to establish a default remote host. With connectionless protocols, you must also be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. + Although intended for connection-oriented protocols, the method also works for connectionless protocols, provided that you first call the , , or method to establish a default remote host. With connectionless protocols, you must also be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. - The method is optimized according to the operating system on which it is used. On Windows server editions, the method is optimized for high performance. + The method is optimized according to the operating system on which it is used. On Windows server editions, the method is optimized for high performance. - On Windows client editions, the method is optimized for minimum memory and resource utilization. + On Windows client editions, the method is optimized for minimum memory and resource utilization. - Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state + Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state ]]> @@ -13148,7 +13148,7 @@ This member outputs trace information when you enable network tracing in your ap calls only. If the time-out period is exceeded, the method will throw a . + This option applies to synchronous calls only. If the time-out period is exceeded, the method will throw a . ## Examples The following code example demonstrates the use of the property. @@ -13227,13 +13227,13 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0, the number of bytes to send defaults to the size of the `buffer` parameter, and the value defaults to 0. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. + Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. - Blocking sockets will block until the all of the bytes in the buffer are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + Blocking sockets will block until the all of the bytes in the buffer are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -13374,13 +13374,13 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0, and the number of bytes to send defaults to the size of the `buffer`. If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. + Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. - Blocking sockets will block until the requested all of the bytes in the `buffer` are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + Blocking sockets will block until the requested all of the bytes in the `buffer` are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -13389,7 +13389,7 @@ This member outputs trace information when you enable network tracing in your ap > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example sends a connectionless datagram to the specified remote host. are passed to the method. + The following code example sends a connectionless datagram to the specified remote host. are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet6"::: @@ -13583,13 +13583,13 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0. If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. + Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. - Blocking sockets will block until the requested number of bytes are sent. Since a nonblocking completes immediately, it might not send all of the bytes requested in a single operation. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + Blocking sockets will block until the requested number of bytes are sent. Since a nonblocking completes immediately, it might not send all of the bytes requested in a single operation. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -13598,7 +13598,7 @@ This member outputs trace information when you enable network tracing in your ap > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example sends a connectionless datagram to the specified remote host. The size and are passed to the method. + The following code example sends a connectionless datagram to the specified remote host. The size and are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet7"::: @@ -13683,13 +13683,13 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, if you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. + Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. - Blocking sockets will block until the requested number of bytes are sent. Since a non-blocking completes immediately, it might not send all of the bytes requested in a single operation. It is your applications responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + Blocking sockets will block until the requested number of bytes are sent. Since a non-blocking completes immediately, it might not send all of the bytes requested in a single operation. It is your applications responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -13698,7 +13698,7 @@ This member outputs trace information when you enable network tracing in your ap > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example sends a connectionless datagram to the specified remote host. The offset, size, and are passed to the method. + The following code example sends a connectionless datagram to the specified remote host. The offset, size, and are passed to the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Receive/source.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Receive/source.vb" id="Snippet8"::: @@ -13795,33 +13795,33 @@ This member outputs trace information when you enable network tracing in your ap method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. + The method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. The following properties and events on the object are required to successfully call this method: -- +- -- +- -- +- -- +- - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. + If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. - If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. + If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. - If you want to send data to a broadcast address, you must first call the method and set the socket option for to true. You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you want to send data to a broadcast address, you must first call the method and set the socket option for to true. You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the DontRoute flag in the property, the data you are sending will not be routed. - For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport. If the size of the buffer exceeds the maximum packet size of the underlying service provider, the datagram is not sent and will throw a . The successful completion of a method does not indicate that the data was successfully delivered. + For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport. If the size of the buffer exceeds the maximum packet size of the underlying service provider, the datagram is not sent and will throw a . The successful completion of a method does not indicate that the data was successfully delivered. ]]> @@ -14159,11 +14159,11 @@ This member outputs trace information when you enable network tracing in your ap method enables restricting an a IPv6 or IP socket to listen on a specified scope, such as addresses with the same link local or site local prefix. This socket option enables applications to place access restrictions on IPv6 or IP sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This socket option can also be used to remove access restrictions if the `level` parameter is set to . This socket option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. + The method enables restricting an a IPv6 or IP socket to listen on a specified scope, such as addresses with the same link local or site local prefix. This socket option enables applications to place access restrictions on IPv6 or IP sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This socket option can also be used to remove access restrictions if the `level` parameter is set to . This socket option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. This socket option has defined protection levels specified in the enumeration. - The method is used to enable or disable Network Address Traversal (NAT) for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. + The method is used to enable or disable Network Address Traversal (NAT) for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. When the `level` parameter is set to , or , this explicitly disables NAT traversal for a instance. @@ -14302,7 +14302,7 @@ The options are grouped by level of protocol support. - Listed below are the various options that can be set using this overload. These options are grouped by the appropriate value. If you intend to set any of these options, be sure to use the appropriate value for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. + Listed below are the various options that can be set using this overload. These options are grouped by the appropriate value. If you intend to set any of these options, be sure to use the appropriate value for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. options that can be set using this overload. @@ -14419,7 +14419,7 @@ The This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example sets the and time-out values. + The following code example sets the and time-out values. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet1"::: @@ -14489,7 +14489,7 @@ The options determine the behavior of the current . For an option with a data type, specify a nonzero value to enable the option, and a zero value to disable the option. For an option with an integer data type, specify the appropriate value. options are grouped by level of protocol support. - Listed below are the various options that can be set using this overload. These options are grouped by the appropriate . If you intend to set any of these options, be sure to use the appropriate for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. + Listed below are the various options that can be set using this overload. These options are grouped by the appropriate . If you intend to set any of these options, be sure to use the appropriate for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. options that can be set using this overload. @@ -14562,7 +14562,7 @@ The This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example sets the and time-out values. + The following code example sets the and time-out values. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet0"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet0"::: @@ -14630,13 +14630,13 @@ The options determine the behavior of the current . Use this overload to set the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to get the current value of any of the options listed above, use the method. + options determine the behavior of the current . Use this overload to set the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to get the current value of any of the options listed above, use the method. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples - The following code example sets the and time out values. + The following code example sets the and time out values. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet1"::: @@ -14703,9 +14703,9 @@ The , always call the method before closing the . This ensures that all data is sent and received on the connected socket before it is closed. + When using a connection-oriented , always call the method before closing the . This ensures that all data is sent and received on the connected socket before it is closed. - Call the method to free all managed and unmanaged resources associated with the . Do not attempt to reuse the after closing. + Call the method to free all managed and unmanaged resources associated with the . Do not attempt to reuse the after closing. The following table shows the enumeration values that are valid for the `how` parameter. @@ -14715,26 +14715,26 @@ The .| |Both|Disable both sending and receiving on this .| - Setting `how` to specifies that subsequent calls to are not allowed. If you are using a connectionless , specifying will have no effect. + Setting `how` to specifies that subsequent calls to are not allowed. If you are using a connectionless , specifying will have no effect. - Setting `how` to specifies that subsequent calls to are not allowed. This has no effect on lower protocol layers. If you are using a connection-oriented protocol, the connection is terminated if either of the following conditions exist after a call to : + Setting `how` to specifies that subsequent calls to are not allowed. This has no effect on lower protocol layers. If you are using a connection-oriented protocol, the connection is terminated if either of the following conditions exist after a call to : - Data is in the incoming network buffer waiting to be received. - More data has arrived. - If you are using a connectionless protocol, datagrams are accepted and queued. However, if no buffer space is available for additional incoming datagrams, they will be discarded and no error will be returned to the sender. Using on a connectionless is not recommended. + If you are using a connectionless protocol, datagrams are accepted and queued. However, if no buffer space is available for additional incoming datagrams, they will be discarded and no error will be returned to the sender. Using on a connectionless is not recommended. Setting `how` to disables both sends and receives as described above. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example uses to disable the . + The following code example uses to disable the . :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Close/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Close/source.vb" id="Snippet1"::: @@ -14800,7 +14800,7 @@ The is read-only and is set when the is created. + is read-only and is set when the is created. ## Examples The following code example displays the , , and to the console. @@ -15124,7 +15124,7 @@ Call IDisposable.Dispose when you are finished using the you intend to call on. Otherwise, the Framework may assign a completion port to the socket, which would prohibit the use of . +.NET Framework only: Set this property to `true` for a you intend to call on. Otherwise, the Framework may assign a completion port to the socket, which would prohibit the use of . On .NET 5+ (include .NET Core) versions, the value of this property is always `false`, and you cannot change its value. diff --git a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml index 0ee7a3a5437..ab070f884c8 100644 --- a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml +++ b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml @@ -86,10 +86,8 @@ The lifetime of the new asynchronous socket operation context object is determined by references by the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to an asynchronous socket operation context object after it is submitted as a parameter to one of the asynchronous socket operation methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the context so that it can be reused for a future asynchronous socket operation. - - ## Examples - The following code example implements the connection logic for the socket server that uses the class. After accepting a connection, all data read from the client is sent back to the client. The read and echo back to the client pattern is continued until the client disconnects. The BufferManager class that is used by this example is displayed in the code example for the method. The SocketAsyncEventArgsPool class that is used in this example is displayed in the code example for the constructor. + The following code example implements the connection logic for the socket server that uses the class. After accepting a connection, all data read from the client is sent back to the client. The read and echo back to the client pattern is continued until the client disconnects. The BufferManager class that is used by this example is displayed in the code example for the method. The SocketAsyncEventArgsPool class that is used in this example is displayed in the code example for the constructor. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/SocketAsyncEventArgs/Overview/AsyncSocketServer.cs" id="Snippet3"::: @@ -274,7 +272,7 @@ that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. + This property can be used to provide an already created that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. ]]> @@ -335,9 +333,9 @@ instance. To set the buffer, the method must be used. + This property gets the data buffer currently associated with the instance. To set the buffer, the method must be used. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -409,17 +407,17 @@ and methods. + This property is used with the and methods. - This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. + This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. - If the property is set to a non-null value, the property must be null and is ignored by the and methods. + If the property is set to a non-null value, the property must be null and is ignored by the and methods. - If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. + If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. - If the property is set to a non-null value, the and methods will throw an . + If the property is set to a non-null value, the and methods will throw an . - The parameter is ignored by the and methods. + The parameter is ignored by the and methods. ]]> @@ -484,7 +482,7 @@ ## Remarks This property provides the number of bytes transferred in an asynchronous socket operation that can receive or send data. If zero is returned from a read operation, the remote end has closed the connection. - This property is set by all asynchronous socket operations except the method. + This property is set by all asynchronous socket operations except the method. ]]> @@ -678,7 +676,7 @@ method, this property contains the newly created and connected object. + After successful completion of the method, this property contains the newly created and connected object. ]]> @@ -738,9 +736,9 @@ method. + This property is set by calling the method. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -810,7 +808,7 @@ method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. + This property is used to alter the behavior of method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. ]]> @@ -1060,9 +1058,9 @@ ## Remarks -This property gets the data buffer currently associated with the instance. To set the buffer, the method must be used. +This property gets the data buffer currently associated with the instance. To set the buffer, the method must be used. -This property is used with the , , , , , , and methods. +This property is used with the , , , , , , and methods. ]]> @@ -1129,11 +1127,11 @@ This property is used with the property. This value is set by calling the method. + This property describes the starting byte offset of data in the property. This value is set by calling the method. This property does not apply to the property. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -1203,7 +1201,7 @@ This property is used with the class. - The caller's method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the method must contain program logic to finish processing the asynchronous socket operation for the client. + The caller's method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the method must contain program logic to finish processing the asynchronous socket operation for the client. When an asynchronous operation is signaled, the application uses the object parameter to obtain status of the completed asynchronous socket operation. @@ -1272,9 +1270,9 @@ This property is used with the method. + This property provides information about a packet received using the method. - This property is used with the method. + This property is used with the method. ]]> @@ -1343,11 +1341,11 @@ This property is used with the method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. + This property specifies the remote endpoint. This property can specify the remote endpoint to which to connect using the method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. This remote endpoint specified by this property can include an IPv4 or IPv6 address. - This property is used with the , , , or methods. + This property is used with the , , , or methods. ]]> @@ -1419,7 +1417,7 @@ This property is used with the method. + The array of buffers can represent a file or files in memory or a set of memory data buffers. This property is used with the method. ]]> @@ -1482,7 +1480,7 @@ This property is used with the that are used by the method. + This property specifies the that are used by the method. ]]> @@ -1565,7 +1563,7 @@ This property is used with the property to null and the and properties to zero. + This method sets the property to null and the and properties to zero. ]]> @@ -1677,7 +1675,7 @@ This method sets the ## Remarks The `offset` and `count` parameters can't be negative numbers. The combination of the `offset` and `count` parameters must be in bounds of the buffer array in the property. - This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. + This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. This method does not change the property. @@ -1950,7 +1948,7 @@ This method sets the ## Remarks The property specifies the bitwise combination of the to be used for an asynchronous socket operation. - This property is used with the , , , and methods. + This property is used with the , , , and methods. ]]> diff --git a/xml/System.Net.Sockets/SocketException.xml b/xml/System.Net.Sockets/SocketException.xml index b2647d8527d..707b65932d3 100644 --- a/xml/System.Net.Sockets/SocketException.xml +++ b/xml/System.Net.Sockets/SocketException.xml @@ -73,7 +73,7 @@ ## Remarks A is thrown by the and classes when an error occurs with the network. - The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> @@ -133,7 +133,7 @@ constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> @@ -192,7 +192,7 @@ constructor sets the property to `errorCode`. + The constructor sets the property to `errorCode`. ]]> diff --git a/xml/System.Net.Sockets/SocketInformation.xml b/xml/System.Net.Sockets/SocketInformation.xml index ed1a30127b3..db1f6e17d5c 100644 --- a/xml/System.Net.Sockets/SocketInformation.xml +++ b/xml/System.Net.Sockets/SocketInformation.xml @@ -56,11 +56,11 @@ Encapsulates the information that is necessary to duplicate a . - creates a instance for use with the constructor. - + creates a instance for use with the constructor. + ]]> @@ -118,11 +118,11 @@ Gets or sets the options for a . A instance. - , , , and . - + , , , and . + ]]> diff --git a/xml/System.Net.Sockets/SocketOptionLevel.xml b/xml/System.Net.Sockets/SocketOptionLevel.xml index e0f03a01270..dfd6fceefb9 100644 --- a/xml/System.Net.Sockets/SocketOptionLevel.xml +++ b/xml/System.Net.Sockets/SocketOptionLevel.xml @@ -49,7 +49,7 @@ enumeration defines the socket option levels that can be passed to the and methods. enumerated values are grouped by . + The enumeration defines the socket option levels that can be passed to the and methods. enumerated values are grouped by . **Note** To use IPv6 on Windows XP, install Advance Networking Pack for Windows XP. @@ -57,7 +57,7 @@ ## Examples The following example uses this enumeration to set socket options. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/SocketOptionName.xml b/xml/System.Net.Sockets/SocketOptionName.xml index d48bffdd9af..569cc2da8d1 100644 --- a/xml/System.Net.Sockets/SocketOptionName.xml +++ b/xml/System.Net.Sockets/SocketOptionName.xml @@ -49,13 +49,13 @@ enumeration defines the name of each configuration option. Sockets can be configured with the method. + The enumeration defines the name of each configuration option. Sockets can be configured with the method. ## Examples The following code example uses this enumeration to set socket options. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/LingerTime/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/LingerTime/source.vb" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/SocketShutdown.xml b/xml/System.Net.Sockets/SocketShutdown.xml index 959b435e3c1..e0185833021 100644 --- a/xml/System.Net.Sockets/SocketShutdown.xml +++ b/xml/System.Net.Sockets/SocketShutdown.xml @@ -51,11 +51,11 @@ Defines constants that are used by the method. - enumeration defines the values that can be passed to the method. - + enumeration defines the values that can be passed to the method. + ]]> diff --git a/xml/System.Net.Sockets/TcpClient.xml b/xml/System.Net.Sockets/TcpClient.xml index 02f33d3943e..6c53baeda89 100644 --- a/xml/System.Net.Sockets/TcpClient.xml +++ b/xml/System.Net.Sockets/TcpClient.xml @@ -64,7 +64,7 @@ In order for `TcpClient` to connect and exchange data, a or created with the TCP must be listening for incoming connection requests. You can connect to this listener in one of the following two ways: -- Create a `TcpClient` and call one of the three available methods. +- Create a `TcpClient` and call one of the three available methods. - Create a `TcpClient` using the host name and port number of the remote host. This constructor will automatically attempt a connection. @@ -145,7 +145,7 @@ and allows the underlying service provider to assign the most appropriate local IP address and port number. You must first call the method before sending and receiving data. + This constructor creates a new and allows the underlying service provider to assign the most appropriate local IP address and port number. You must first call the method before sending and receiving data. > [!NOTE] > On .NET Framework, this constructor works only with IPv4 address types. @@ -211,7 +211,7 @@ ## Remarks This constructor creates a new and binds it to the specified by the `localEP` parameter. Before you call this constructor, you must create an `IPEndPoint` using the IP address and port number from which you intend to send and receive data. You do not need to specify a local IP address and port number before connecting and communicating. If you create a `TcpClient` using any other constructor, the underlying service provider will assign the most appropriate local IP address and port number. - You must call the method before sending and receiving data. + You must call the method before sending and receiving data. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -343,10 +343,10 @@ ## Remarks This constructor creates a new and makes a synchronous connection attempt to the provided host name and port number. The underlying service provider will assign the most appropriate local IP address and port number. `TcpClient` will block until it either connects or fails. This constructor allows you to initialize, resolve the DNS host name, and connect in one convenient step. - If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. + If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -474,9 +474,9 @@ to get the data. The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, `Available` returns 0. +The `Available` property is a way to determine whether data is queued for reading. If data is available, call to get the data. The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, `Available` returns 0. - If the remote host shuts down or closes the connection, `Available` may throw a . If you receive a `SocketException`, use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If the remote host shuts down or closes the connection, `Available` may throw a . If you receive a `SocketException`, use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -568,9 +568,9 @@ The `Available` property is a way to determine whether data is queued for readin method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous `BeginConnect` operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -653,13 +653,13 @@ The `Available` property is a way to determine whether data is queued for readin method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous `BeginConnect` operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. + This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. > [!NOTE] > If you receive NotSupportedException with message `This protocol version is not supported` while using IPv6 address, then make sure you enabled IPv6 in constructor by passing . @@ -740,9 +740,9 @@ The `Available` property is a way to determine whether data is queued for readin method. Typically, the method is invoked by the `asyncCallback` delegate. + The asynchronous `BeginConnect` operation must be completed by calling the method. Typically, the method is invoked by the `asyncCallback` delegate. - This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. + This method does not block until the operation completes. To block until the operation completes, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -945,10 +945,10 @@ The `Available` property is a way to determine whether data is queued for readin . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1019,10 +1019,10 @@ The `Available` property is a way to determine whether data is queued for readin and port number. The method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified and port number. The method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1094,10 +1094,10 @@ The `Available` property is a way to determine whether data is queued for readin method, which can return multiple IP addresses for a single host. Call the `Connect` method to establish a synchronous remote host connection to the host specified by the array of elements and the port number. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call the `Connect` method to establish a synchronous remote host connection to the host specified by the array of elements and the port number. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1170,12 +1170,12 @@ The `Available` property is a way to determine whether data is queued for readin method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified host name and port number. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. If IPv6 is enabled and the `Connect(String, Int32)` method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1245,10 +1245,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned object will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you've obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you've obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1312,10 +1312,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned Returns object will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1385,10 +1385,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned Returns object will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call this method to establish a synchronous remote host connection to the host specified by the array of elements and the port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call this method to establish a synchronous remote host connection to the host specified by the array of elements and the port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1447,10 +1447,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned Returns object will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified . Before you call `Connect`, you must create an instance of the `IPEndPoint` class using an IP address and a port number. Use this `IPEndPoint` as the `remoteEP` parameter. The `Connect` method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1515,12 +1515,12 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned Returns object will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified host name and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified host name and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. - If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. + If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1579,10 +1579,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned task will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified IP address and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified IP address and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1644,10 +1644,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned task will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call this method to establish a synchronous remote host connection to the host specified by the array of IP addresses and the port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call this method to establish a synchronous remote host connection to the host specified by the array of IP addresses and the port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1710,12 +1710,12 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks This operation will not block. The returned task will complete after the TCP connection has been established. This method does not block the calling thread while the connection request is underway. - Call this method to establish a synchronous remote host connection to the specified host name and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. + Call this method to establish a synchronous remote host connection to the specified host name and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this `NetworkStream` to send and receive data. - If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. + If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1778,7 +1778,7 @@ The `Available` property is a way to determine whether data is queued for readin socket as of the last I/O operation. When it returns `false`, the `Client` socket was either never connected, or is no longer connected. + The `Connected` property gets the connection state of the socket as of the last I/O operation. When it returns `false`, the `Client` socket was either never connected, or is no longer connected. Because the `Connected` property only reflects the state of the connection as of the most recent operation, you should attempt to send or receive a message to determine the current state. After the message send fails, this property no longer returns `true`. Note that this behavior is by design. You cannot reliably test the state of the connection because, in the time between the test and a send/receive, the connection could have been lost. Your code should assume the socket is connected, and gracefully handle failed transmissions. @@ -1946,10 +1946,10 @@ The `Available` property is a way to determine whether data is queued for readin method. + This method blocks until the operation is complete. To perform this operation synchronously, use a method. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ]]> @@ -2006,7 +2006,7 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port. You can use the `ExclusiveAddressUse` property to prevent multiple clients from using a specific port. - This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the method, and you cannot subsequently set the `ExclusiveAddressUse` property. + This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the method, and you cannot subsequently set the `ExclusiveAddressUse` property. @@ -2065,7 +2065,7 @@ The `Available` property is a way to determine whether data is queued for readin . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. The class finalizer closes the TCP connection and releases all managed resources associated with the `TcpClient`. These resources include the underlying used for connecting with the remote host, and the used to send and receive data. The finalizer does not release any unmanaged resources. @@ -2124,10 +2124,10 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks The `GetStream` method returns a that you can use to send and receive data. The `NetworkStream` class inherits from the class, which provides a rich collection of methods and properties used to facilitate network communications. - You must call the method first, or the method will throw an . After you have obtained the `NetworkStream`, call the method to send data to the remote host. Call the method to receive data arriving from the remote host. Both of these methods block until the specified operation is performed. You can avoid blocking on a read operation by checking the property. A `true` value means that data has arrived from the remote host and is available for reading. In this case, is guaranteed to complete immediately. If the remote host has shutdown its connection, will immediately return with zero bytes. + You must call the method first, or the method will throw an . After you have obtained the `NetworkStream`, call the method to send data to the remote host. Call the method to receive data arriving from the remote host. Both of these methods block until the specified operation is performed. You can avoid blocking on a read operation by checking the property. A `true` value means that data has arrived from the remote host and is available for reading. In this case, is guaranteed to complete immediately. If the remote host has shutdown its connection, will immediately return with zero bytes. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -2135,7 +2135,7 @@ The `GetStream` method returns a that yo ## Examples - The following code example uses `GetStream` to obtain the underlying . After obtaining the , it sends and receives using its and methods. + The following code example uses `GetStream` to obtain the underlying . After obtaining the , it sends and receives using its and methods. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpClient/.ctor/source.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpClient/.ctor/source.vb" id="Snippet14"::: @@ -2203,13 +2203,13 @@ The `GetStream` method returns a that yo method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. + The `LingerState` property changes the way method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. - This property controls the length of time that the TCP connection will remain open after a call to when data remains to be sent. When you call the method, data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the method drops the connection. + This property controls the length of time that the TCP connection will remain open after a call to when data remains to be sent. When you call the method, data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the method drops the connection. To enable lingering, create a instance containing the desired values, and set the `LingerState` property to this instance. - The following table describes the behavior of the method for the possible values of the property and the property stored in the `LingerState` property. + The following table describes the behavior of the method for the possible values of the property and the property stored in the `LingerState` property. |LingerState.Enabled|LingerState.LingerTime|Behavior| |-------------------------|----------------------------|--------------| @@ -2347,7 +2347,7 @@ The `GetStream` method returns a that yo ## Remarks The `ReceiveBufferSize` property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation. This property actually manipulates the network buffer space allocated for receiving incoming data. - Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the `Read` method a very large application buffer. + Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the `Read` method a very large application buffer. If the network buffer is smaller than the amount of data you request in the `Read` method, you will not be able to retrieve the desired amount of data in one read operation. This incurs the overhead of additional calls to the `Read` method. @@ -2420,7 +2420,7 @@ The `GetStream` method returns a that yo method will block until it is able to receive data. This time is measured in milliseconds. If the time-out expires before `Read` successfully completes, throws a . There is no time-out by default. + The `ReceiveTimeout` property determines the amount of time that the method will block until it is able to receive data. This time is measured in milliseconds. If the time-out expires before `Read` successfully completes, throws a . There is no time-out by default. @@ -2486,7 +2486,7 @@ The `GetStream` method returns a that yo method. This property actually manipulates the network buffer space allocated for send operation. + The `SendBufferSize` property gets or sets the number of bytes that you are expecting to send in each call to the method. This property actually manipulates the network buffer space allocated for send operation. Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the property to set this size. If your application will be sending bulk data, you should pass the `Write` method a very large application buffer. @@ -2556,9 +2556,9 @@ The `GetStream` method returns a that yo method will block until it is able to return successfully. This time is measured in milliseconds. + The `SendTimeout` property determines the amount of time that the method will block until it is able to return successfully. This time is measured in milliseconds. - After you call the method, the underlying returns the number of bytes actually sent to the host. The `SendTimeout` property determines the amount of time a will wait before receiving the number of bytes returned. If the time-out expires before the `Send` method successfully completes, `TcpClient` will throw a . There is no time-out by default. + After you call the method, the underlying returns the number of bytes actually sent to the host. The `SendTimeout` property determines the amount of time a will wait before receiving the number of bytes returned. If the time-out expires before the `Send` method successfully completes, `TcpClient` will throw a . There is no time-out by default. diff --git a/xml/System.Net.Sockets/TcpListener.xml b/xml/System.Net.Sockets/TcpListener.xml index c570051e5d0..f9b0a003526 100644 --- a/xml/System.Net.Sockets/TcpListener.xml +++ b/xml/System.Net.Sockets/TcpListener.xml @@ -67,12 +67,12 @@ ## Remarks The class provides simple methods that listen for and accept incoming connection requests in blocking synchronous mode. You can use either a or a to connect with a . Create a using an , a Local IP address and port number, or just a port number. Specify for the local IP address and 0 for the local port number if you want the underlying service provider to assign those values for you. If you choose to do this, you can use the property to identify the assigned information, after the socket has connected. - Use the method to begin listening for incoming connection requests. will queue incoming connections until you either call the method or it has queued . Use either or to pull a connection from the incoming connection request queue. These two methods will block. If you want to avoid blocking, you can use the method first to determine if connection requests are available in the queue. + Use the method to begin listening for incoming connection requests. will queue incoming connections until you either call the method or it has queued . Use either or to pull a connection from the incoming connection request queue. These two methods will block. If you want to avoid blocking, you can use the method first to determine if connection requests are available in the queue. - Call the method to close the . + Call the method to close the . > [!NOTE] -> The method does not close any accepted connections. You are responsible for closing these separately. +> The method does not close any accepted connections. You are responsible for closing these separately. @@ -160,11 +160,11 @@ [!NOTE] -> This constructor is obsolete. Use the or constructors. +> This constructor is obsolete. Use the or constructors. This constructor allows you to specify the port number on which to listen for incoming connection attempts. With this constructor, the underlying service provider assigns the most appropriate network address. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. - Call the method to begin listening for incoming connection attempts. + Call the method to begin listening for incoming connection attempts. ]]> @@ -221,7 +221,7 @@ If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. - Call the method to begin listening for incoming connection attempts. + Call the method to begin listening for incoming connection attempts. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -290,7 +290,7 @@ ## Remarks This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts. Before calling this constructor you must first create an using the desired local address. Pass this to the constructor as the `localaddr` parameter. If you do not care which local address is assigned, specify for the `localaddr` parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 65535. If you use this approach, you can discover what local network address and port number has been assigned by using the property. - Call the method to begin listening for incoming connection attempts. + Call the method to begin listening for incoming connection attempts. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -357,9 +357,9 @@ is a blocking method that returns a that you can use to send and receive data. If you want to avoid blocking, use the method to determine if connection requests are available in the incoming connection queue. + is a blocking method that returns a that you can use to send and receive data. If you want to avoid blocking, use the method to determine if connection requests are available in the incoming connection queue. - The returned is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. + The returned is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -367,7 +367,7 @@ ## Examples - In the following code example, the method is used to return a . This is used to communicate with the newly connected client. + In the following code example, the method is used to return a . This is used to communicate with the newly connected client. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/.ctor/source.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/.ctor/source.vb" id="Snippet4"::: @@ -423,9 +423,9 @@ object will complete after the socket connection has been accepted. + This operation will not block. The returned object will complete after the socket connection has been accepted. - The returned in is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. + The returned in is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -480,9 +480,9 @@ object will complete after the socket connection has been accepted. + This operation will not block. The returned object will complete after the socket connection has been accepted. - The returned in is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. + The returned in is initialized with the IP address and port number of the remote host. You can use any of the and methods available in the class to communicate with the remote host. When you are finished using the , be sure to call its method. If your application is relatively simple, consider using the method rather than the method. provides you with simple methods for sending and receiving data over a network in blocking synchronous mode. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -538,9 +538,9 @@ is a blocking method that returns a that you can use to send and receive data. Use the method to determine if connection requests are available in the incoming connection queue if you want to avoid blocking. + is a blocking method that returns a that you can use to send and receive data. Use the method to determine if connection requests are available in the incoming connection queue if you want to avoid blocking. - Use the method to obtain the underlying of the returned . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using . + Use the method to obtain the underlying of the returned . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -548,7 +548,7 @@ ## Examples - In the following code example, the method is used to return a . This is used to communicate with the newly connected client. + In the following code example, the method is used to return a . This is used to communicate with the newly connected client. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/AcceptTcpClient/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/AcceptTcpClient/source.vb" id="Snippet1"::: @@ -606,9 +606,9 @@ object will complete after the TCP connection has been accepted. + This operation will not block. The returned object will complete after the TCP connection has been accepted. - Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . + Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -665,9 +665,9 @@ object will complete after the TCP connection has been accepted. + This operation will not block. The returned object will complete after the TCP connection has been accepted. - Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . + Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -730,7 +730,7 @@ can use this property to determine if the is currently listening for incoming connection attempts. The property can be used to avoid redundant attempts. + Classes deriving from can use this property to determine if the is currently listening for incoming connection attempts. The property can be used to avoid redundant attempts. ]]> @@ -787,13 +787,13 @@ method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. + The method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. When the `allowed` parameter is false, the option on the associated socket is set to . This explicitly disables NAT traversal for a instance. When the `allowed` parameter is true, the option on the associated socket is set to . This may allow NAT traversal for a depending on firewall rules in place on the system. - The method must be invoked prior to calling the method to begin listening for incoming connection requests (before the socket is bound). If method is called after the method, then an will be thrown. + The method must be invoked prior to calling the method to begin listening for incoming connection requests (before the socket is bound). If method is called after the method, then an will be thrown. A Teredo address is an IPv6 address with the prefix of 2001::/32. Teredo addresses can be returned through normal DNS name resolution or enumerated as an IPv6 address assigned to a local interface. @@ -862,9 +862,9 @@ operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. - This method does not block until the operation completes. To block until the operation completes, use the method. + This method does not block until the operation completes. To block until the operation completes, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -938,9 +938,9 @@ operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. - This method does not block until the operation completes. To block until the operation completes, use the method. + This method does not block until the operation completes. To block until the operation completes, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -1078,7 +1078,7 @@ method. + This method blocks until the operation is complete. To perform this operation synchronously, use the method. > [!NOTE] > You can call the property of the returned to identify the remote host's network address and port number. @@ -1146,10 +1146,10 @@ method. + This method blocks until the operation is complete. To perform this operation synchronously, use the method. > [!NOTE] -> You can call the property of the underlying socket () to identify the remote host's network address and port number. +> You can call the property of the underlying socket () to identify the remote host's network address and port number. > [!NOTE] > If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -1208,7 +1208,7 @@ ## Remarks By default, multiple listeners can listen to a specific port. However, only one of the listeners can perform operations on the network traffic sent to the port. If more than one listener attempts to bind to a particular port, then the one with the more specific IP address handles the network traffic sent to that port. You can use the property to prevent multiple listeners from listening to a specific port. - Set this property before calling , or call the method and then set this property. + Set this property before calling , or call the method and then set this property. @@ -1365,12 +1365,12 @@ The class finalizer free resources associa and methods block execution until the method has queued an incoming connection request, the method can be used to determine if connections are available before attempting to accept them. + This non-blocking method determines if there are any pending connection requests. Because the and methods block execution until the method has queued an incoming connection request, the method can be used to determine if connections are available before attempting to accept them. ## Examples - The following code example checks the method. If a connection request is waiting to be accepted, then a call to the method is made. + The following code example checks the method. If a connection request is waiting to be accepted, then a call to the method is made. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/LocalEndpoint/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/LocalEndpoint/source.vb" id="Snippet1"::: @@ -1439,7 +1439,7 @@ The class finalizer free resources associa creates a to listen for incoming client connection requests. Classes deriving from can use this property to get this . Use the underlying returned by the property if you require access beyond that which provides. > [!NOTE] -> The property only returns the used to listen for incoming client connection requests. Use the method to accept a pending connection request and obtain a for sending and receiving data. You can also use the method to accept a pending connection request and obtain a for sending and receiving data. +> The property only returns the used to listen for incoming client connection requests. Use the method to accept a pending connection request and obtain a for sending and receiving data. You can also use the method to accept a pending connection request and obtain a for sending and receiving data. @@ -1516,11 +1516,11 @@ The class finalizer free resources associa method initializes the underlying , binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, the method will queue the request and continue listening for additional requests until you call the method. If receives a connection request after it has already queued the maximum number of connections, it will throw a on the client. + The method initializes the underlying , binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, the method will queue the request and continue listening for additional requests until you call the method. If receives a connection request after it has already queued the maximum number of connections, it will throw a on the client. - To remove a connection from the incoming connection queue, use either the method or the method. The method will remove a connection from the queue and return a that you can use to send and receive data. The method will return a that you can use to do the same. If your application only requires synchronous I/O, use . For more detailed behavioral control, use . Both of these methods block until a connection request is available in the queue. + To remove a connection from the incoming connection queue, use either the method or the method. The method will remove a connection from the queue and return a that you can use to send and receive data. The method will return a that you can use to do the same. If your application only requires synchronous I/O, use . For more detailed behavioral control, use . Both of these methods block until a connection request is available in the queue. - Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. + Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1528,7 +1528,7 @@ The class finalizer free resources associa ## Examples - The following code example demonstrates how is used to listen for incoming client connection attempts. + The following code example demonstrates how is used to listen for incoming client connection attempts. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/BeginAcceptSocket/tcpserver.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/ExclusiveAddressUse/tcpserver.vb" id="Snippet3"::: @@ -1588,11 +1588,11 @@ The class finalizer free resources associa method initializes the underlying , binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, will queue the request and continue listening for additional requests until you call the method. If receives a connection request after it has already queued the maximum number of connections it will throw a on the client. + The method initializes the underlying , binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, will queue the request and continue listening for additional requests until you call the method. If receives a connection request after it has already queued the maximum number of connections it will throw a on the client. - To remove a connection from the incoming connection queue, use either the method or the method. The method will remove a connection from the queue and return a that you can use to send and receive data. The method will return a that you can use to do the same. If your application only requires synchronous I/O, use the . For more detailed behavioral control, use method. Both of these methods block until a connection request is available in the queue. + To remove a connection from the incoming connection queue, use either the method or the method. The method will remove a connection from the queue and return a that you can use to send and receive data. The method will return a that you can use to do the same. If your application only requires synchronous I/O, use the . For more detailed behavioral control, use method. Both of these methods block until a connection request is available in the queue. - Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. + Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. > [!NOTE] > Use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -1603,7 +1603,7 @@ The class finalizer free resources associa ## Examples - The following code example demonstrates how is used to listen for incoming client connection attempts. + The following code example demonstrates how is used to listen for incoming client connection attempts. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/BeginAcceptSocket/tcpserver.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/ExclusiveAddressUse/tcpserver.vb" id="Snippet3"::: @@ -1664,7 +1664,7 @@ The class finalizer free resources associa closes the listener. Any unaccepted connection requests in the queue will be lost. Remote hosts waiting for a connection to be accepted will throw a . You are responsible for closing your accepted connections separately. + closes the listener. Any unaccepted connection requests in the queue will be lost. Remote hosts waiting for a connection to be accepted will throw a . You are responsible for closing your accepted connections separately. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1672,7 +1672,7 @@ The class finalizer free resources associa ## Examples - The following code example demonstrates using the method to close the underlying . + The following code example demonstrates using the method to close the underlying . :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/Overview/tcpserver.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/Overview/tcpserver.vb" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/TransmitFileOptions.xml b/xml/System.Net.Sockets/TransmitFileOptions.xml index dab04df9412..5dbfc366378 100644 --- a/xml/System.Net.Sockets/TransmitFileOptions.xml +++ b/xml/System.Net.Sockets/TransmitFileOptions.xml @@ -55,13 +55,13 @@ ## Remarks > [!NOTE] -> The flags `Disconnect` and `ReuseSocket` return the socket to a disconnected, reusable state after the file has been transmitted. These flags should not be used on a socket where quality of service (QOS) has been requested, because the service provider might immediately delete any quality of service associated with the socket before the file transfer has completed. The best approach for a QOS-enabled socket is to call when the file transfer has completed, rather than relying on these flags. +> The flags `Disconnect` and `ReuseSocket` return the socket to a disconnected, reusable state after the file has been transmitted. These flags should not be used on a socket where quality of service (QOS) has been requested, because the service provider might immediately delete any quality of service associated with the socket before the file transfer has completed. The best approach for a QOS-enabled socket is to call when the file transfer has completed, rather than relying on these flags. ## Examples - The following example demonstrates the use of `TransmitFileOptions` in a call to . The file "test.txt" is located in the root directory of the local machine. In this example, a prebuffer and postbuffer of data are created and sent to the remote host with the file. To use the system's default thread, `UseDefaultWorkerThread` is specified. - + The following example demonstrates the use of `TransmitFileOptions` in a call to . The file "test.txt" is located in the root directory of the local machine. In this example, a prebuffer and postbuffer of data are created and sent to the remote host with the file. To use the system's default thread, `UseDefaultWorkerThread` is specified. + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/BeginAccept/nclsocketenhancements.cs" id="Snippet4"::: ]]> diff --git a/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml b/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml index def45065849..e5e5d4a1d2e 100644 --- a/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml +++ b/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml @@ -66,7 +66,7 @@ constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. + The constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. @@ -118,11 +118,11 @@ method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from any multicast group participant. The local port and multicast group address are specified in the constructor. + The method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from any multicast group participant. The local port and multicast group address are specified in the constructor. The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . ]]> @@ -175,7 +175,7 @@ method begins an operation of receiving a UDP packet from the joined multicast group from any sender. The local port and multicast group address are specified in the constructor. The multicast client must also have completed a join to the multicast group. + The method begins an operation of receiving a UDP packet from the joined multicast group from any sender. The local port and multicast group address are specified in the constructor. The multicast client must also have completed a join to the multicast group. The method specified in the `callback` parameter is invoked when a packet has received. @@ -250,7 +250,7 @@ method begins an operation of sending a UDP packet to the joined multicast group. + The method begins an operation of sending a UDP packet to the joined multicast group. The client must have completed a join to the multicast group. The destination address specified in the `remoteEndPoint` parameter must have already sent a multicast packet to this receiver. Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. @@ -329,7 +329,7 @@ method begins an operation of sending a UDP packet to the joined multicast group. + The method begins an operation of sending a UDP packet to the joined multicast group. The client must have completed a join to the multicast group. @@ -395,7 +395,7 @@ method blocks multicast packets originating from a specified source address from being received. The client must have completed a join to the multicast group. + The method blocks multicast packets originating from a specified source address from being received. The client must have completed a join to the multicast group. The `sourceAddress` parameter may be either an IPv6 or IPv4 address, but the `sourceAddress` parameter must match the address family of the multicast group that the client joined. @@ -445,9 +445,9 @@ when you are finished using the . The Dispose method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The Dispose method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. + Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> @@ -488,9 +488,9 @@ method completes an asynchronous bind to a socket and join operation to a multicast group. + The method completes an asynchronous bind to a socket and join operation to a multicast group. - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. @@ -540,7 +540,7 @@ method completes an asynchronous operation to receive a packet from a multicast group. + The method completes an asynchronous operation to receive a packet from a multicast group. If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. @@ -588,7 +588,7 @@ method completes an asynchronous operation to send a packet to specified destination address. + The method completes an asynchronous operation to send a packet to specified destination address. If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. @@ -636,7 +636,7 @@ method completes an asynchronous operation to send a packet to a multicast group. + The method completes an asynchronous operation to send a packet to a multicast group. If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. @@ -725,7 +725,7 @@ property gets or sets the size, in bytes, of the receive buffer of the underlying used for multicast receive operations on this instance. Specifically, the property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. + The property gets or sets the size, in bytes, of the receive buffer of the underlying used for multicast receive operations on this instance. Specifically, the property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. The default size of the receive buffer on Windows is 8,192 bytes. @@ -772,7 +772,7 @@ ## Remarks The property gets or sets the size, in bytes, of the send buffer of the underlying Socket used for multicast send operations on this instance. - calls to the or methods will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. + calls to the or methods will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. The default size of the send buffer on Windows is 8,192 bytes. @@ -818,13 +818,13 @@ method unblocks multicast packets originating from a specified source address so they can be received. The specified source address must have previously been blocked by a call to the method. + The method unblocks multicast packets originating from a specified source address so they can be received. The specified source address must have previously been blocked by a call to the method. The client must have completed a join to the multicast group. The `sourceAddress` parameter may be either an IPv6 or IPv4 multicast address. - If the specified source address in the `sourceAddress` parameter was not previously blocked by a call to the method, a is thrown with . + If the specified source address in the `sourceAddress` parameter was not previously blocked by a call to the method, a is thrown with . If there is a socket failure while performing the unblock source operation, a is thrown. The error received is specified as a member of the enumeration. diff --git a/xml/System.Net.Sockets/UdpClient.xml b/xml/System.Net.Sockets/UdpClient.xml index 259fdad80bd..f83071e73cd 100644 --- a/xml/System.Net.Sockets/UdpClient.xml +++ b/xml/System.Net.Sockets/UdpClient.xml @@ -64,19 +64,19 @@ - Create an instance of the class using the remote host name and port number as parameters. -- Create an instance of the class and then call the method. +- Create an instance of the class and then call the method. - You can use any of the send methods provided in the to send data to a remote device. Use the method to receive data from remote hosts. + You can use any of the send methods provided in the to send data to a remote device. Use the method to receive data from remote hosts. > [!NOTE] -> Do not call using a host name or if you have already specified a default remote host. If you do, will throw an exception. +> Do not call using a host name or if you have already specified a default remote host. If you do, will throw an exception. - methods also allow you to send and receive multicast datagrams. Use the method to subscribe a to a multicast group. Use the method to unsubscribe a from a multicast group. + methods also allow you to send and receive multicast datagrams. Use the method to subscribe a to a multicast group. Use the method to unsubscribe a from a multicast group. ## Examples - The following example establishes a connection using the host name `www.contoso.com` on port 11000. A small string message is sent to two separate remote host machines. The method blocks execution until a message is received. Using the passed to , the identity of the responding host is revealed. + The following example establishes a connection using the host name `www.contoso.com` on port 11000. A small string message is sent to two separate remote host machines. The method blocks execution until a message is received. Using the passed to , the identity of the responding host is revealed. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/Overview/source.vb" id="Snippet1"::: @@ -146,7 +146,7 @@ This constructor creates a new and allows the underlying service provider to assign the most appropriate local IPv4 address and port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This constructor is not suitable for joining a multicast group because it does not perform socket binding. Also, it works only with IPv4 address types. @@ -216,7 +216,7 @@ This constructor creates an underlying and binds it to the port number from which you intend to communicate. Use this constructor if you are only interested in setting the local port number. The underlying service provider will assign the local IP address. If you pass 0 to the constructor, the underlying service provider will assign a port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This constructor works only with IPv4 address types. @@ -283,7 +283,7 @@ If this constructor is used, the instance is set with the address family specified by the `localEP` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -350,9 +350,9 @@ If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - The is not suitable for joining a multicast group because it does not perform socket binding. + The is not suitable for joining a multicast group because it does not perform socket binding. ]]> @@ -414,7 +414,7 @@ If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -478,10 +478,10 @@ and establishes a remote host using the `hostname` and `port` parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the method. If you want to specify a remote host in your call to the method, do not use this constructor. + This constructor initializes a new and establishes a remote host using the `hostname` and `port` parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the method. If you want to specify a remote host in your call to the method, do not use this constructor. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -557,7 +557,7 @@ can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the method. If you do establish a default remote host, you cannot specify a remote host in your call to . + Classes deriving from can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the method. If you do establish a default remote host, you cannot specify a remote host in your call to . ]]> @@ -616,7 +616,7 @@ method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. + The method is used to enable or disable NAT traversal for a instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel. When the `allowed` parameter is false, the option on the associated socket is set to . This explicitly disables NAT traversal for a instance. @@ -676,12 +676,12 @@ property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. + The property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. If the remote host shuts down or closes the connection, the property throws a . > [!NOTE] -> If you receive a , use to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -751,16 +751,16 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example uses to asynchronously receive a server response. + The following code example uses to asynchronously receive a server response. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: @@ -851,16 +851,16 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation completes. To block until the operation is complete, use one of the method overloads. + This method does not block until the operation completes. To block until the operation is complete, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example uses to asynchronously send a server request. + The following code example uses to asynchronously send a server request. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: @@ -938,16 +938,16 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. + This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example uses to asynchronously send a server request. + The following code example uses to asynchronously send a server request. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: @@ -1027,16 +1027,16 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. + This method does not block until the operation is complete. To block until the operation is complete, use one of the method overloads. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example uses to asynchronously send a server request. + The following code example uses to asynchronously send a server request. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: @@ -1103,7 +1103,7 @@ creates a used to send and receive data over a network. Classes deriving from can use this property to get or set this . Use the underlying returned from if you require access beyond that which provides. You can also use to set the underlying to an existing . This is useful if you want to take advantage of the simplicity of using a pre-existing . + creates a used to send and receive data over a network. Classes deriving from can use this property to get or set this . Use the underlying returned from if you require access beyond that which provides. You can also use to set the underlying to an existing . This is useful if you want to take advantage of the simplicity of using a pre-existing . @@ -1167,15 +1167,15 @@ disables the underlying and releases all managed and unmanaged resources associated with the . + The disables the underlying and releases all managed and unmanaged resources associated with the . > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples - The following example demonstrates closing a by calling the method. + The following example demonstrates closing a by calling the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/.ctor/source.vb" id="Snippet15"::: @@ -1242,16 +1242,16 @@ method establishes a default remote host using the value specified in the `endPoint` parameter. Once established, you do not have to specify a remote host in each call to the method. + The method establishes a default remote host using the value specified in the `endPoint` parameter. Once established, you do not have to specify a remote host in each call to the method. - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -1320,16 +1320,16 @@ method establishes a default remote host using the values specified in the `addr` and `port` parameters. Once established, you do not have to specify a remote host in each call to the method. + The method establishes a default remote host using the values specified in the `addr` and `port` parameters. Once established, you do not have to specify a remote host in each call to the method. - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -1401,18 +1401,18 @@ method establishes a default remote host using the values specified in the `port` and `hostname` parameters. Once established, you do not have to specify a remote host in each call to the method. + The method establishes a default remote host using the values specified in the `port` and `hostname` parameters. Once established, you do not have to specify a remote host in each call to the method. - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. - If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] -> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. +> Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -1582,7 +1582,7 @@ option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. + Datagrams require fragmentation when their size exceeds the Maximum Transfer Unit (MTU) of the transmission medium. Datagrams may be fragmented by the sending host or by an intermediate router. If a datagram must be fragmented, and the option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. @@ -1653,10 +1653,10 @@ method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. + The method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -1725,7 +1725,7 @@ method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. + The method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -1863,12 +1863,12 @@ ## Remarks This method blocks until the operation is complete. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. ## Examples - The following code example uses to complete an asynchronous receive of a server response. + The following code example uses to complete an asynchronous receive of a server response. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet1"::: @@ -1932,12 +1932,12 @@ ## Remarks This method blocks until the operation is complete. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. ## Examples - The following code example uses to complete an asynchronous send of a server request. + The following code example uses to complete an asynchronous send of a server request. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/BeginReceive/asyncudp.cs" id="Snippet2"::: @@ -1999,7 +1999,7 @@ ## Remarks By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port. You can use the property to prevent multiple clients from using a specific port. - This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property + This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property @@ -2071,20 +2071,20 @@ method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + The method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . > [!NOTE] -> You must create the using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method, or the method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. +> You must create the using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method, or the method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter. - To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. + To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. > [!NOTE] > In the IPv6 case, there are several multicast address ranges you can choose from. Please, refer to the IETF RFC 2375. > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). +> You cannot call on a constructed without a specific local port (that is, using the or constructor). @@ -2159,7 +2159,7 @@ > There are several multicast address ranges to choose from. Refer to the IETF RFC 2375. > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). +> You cannot call on a constructed without a specific local port (that is, using the or constructor). @@ -2222,17 +2222,17 @@ method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + The method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . > [!NOTE] -> You must create the using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. +> You must create the using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. Before joining a multicast group make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept as parameter a port or an endpoint. - To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. + To stop receiving multicasted datagrams, call the method and provide the of the group from which you would like to withdraw. > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). +> You cannot call on a constructed without a specific local port (that is, using the or constructor). @@ -2307,12 +2307,12 @@ > There are several multicast address ranges to choose from. You can find them in the IETF RFC 2375. > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). +> You cannot call on a constructed without a specific local port (that is, using the or constructor). ## Examples - The following code example shows the use of the method. + The following code example shows the use of the method. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet6"::: @@ -2438,19 +2438,19 @@ method will block until a datagram arrives from a remote host. When data is available, the method will read the first enqueued datagram and return the data portion as a byte array. This method populates the `remoteEP` parameter with the and port number of the sender. + The method will block until a datagram arrives from a remote host. When data is available, the method will read the first enqueued datagram and return the data portion as a byte array. This method populates the `remoteEP` parameter with the and port number of the sender. - If you specify a default remote host in the method, the method will accept datagrams from that host only. All other datagrams will be discarded. + If you specify a default remote host in the method, the method will accept datagrams from that host only. All other datagrams will be discarded. - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> If you intend to receive multicasted datagrams, do not call the method prior to calling the method. The you use to receive datagrams must be created using the multicast port number. +> If you intend to receive multicasted datagrams, do not call the method prior to calling the method. The you use to receive datagrams must be created using the multicast port number. ## Examples - The following example demonstrates the method. The method blocks execution until it receives a message. Using the passed to , the identity of the responding host is revealed. + The following example demonstrates the method. The method blocks execution until it receives a message. Using the passed to , the identity of the responding host is revealed. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/.ctor/source.vb" id="Snippet11"::: @@ -2508,14 +2508,14 @@ > object will complete after the UDP packet has been received. + This operation will not block. The returned > object will complete after the UDP packet has been received. - If you specify a default remote host in the method, this method will accept datagrams from that host only. All other datagrams will be discarded. + If you specify a default remote host in the method, this method will accept datagrams from that host only. All other datagrams will be discarded. - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!WARNING] -> If you intend to receive multicasted datagrams, do not call the method prior to calling this method. The you use to receive datagrams must be created using the multicast port number. +> If you intend to receive multicasted datagrams, do not call the method prior to calling this method. The you use to receive datagrams must be created using the multicast port number. ]]> @@ -2654,14 +2654,14 @@ method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + This overload sends datagrams to the remote host established in the method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. + If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. ## Examples - The following example demonstrates the method. You must establish a default remote host prior to using this overload. + The following example demonstrates the method. You must establish a default remote host prior to using this overload. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/.ctor/source.vb" id="Snippet10"::: @@ -2782,17 +2782,17 @@ method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. + The method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!NOTE] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples - The following example demonstrates the method. This example uses an to specify the target host. + The following example demonstrates the method. This example uses an to specify the target host. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/.ctor/source.vb" id="Snippet8"::: @@ -2920,17 +2920,17 @@ method sends datagrams to the values specified by the `hostname` and `port` parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. + The method sends datagrams to the values specified by the `hostname` and `port` parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!NOTE] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples - The following example demonstrates the method. This example uses a host name and a port number to identify the target host. + The following example demonstrates the method. This example uses a host name and a port number to identify the target host. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/.ctor/source.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/.ctor/source.vb" id="Snippet9"::: @@ -3004,9 +3004,9 @@ method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + This overload sends datagrams to the remote host established in the method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. + If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3116,10 +3116,10 @@ ## Remarks This method sends datagrams to the specified endpoint. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!WARNING] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3244,10 +3244,10 @@ ## Remarks This method sends datagrams to the values specified by the `hostname` and `port` parameters. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!WARNING] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . diff --git a/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml b/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml index 0f0873ef581..ed74f474a64 100644 --- a/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml +++ b/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml @@ -79,7 +79,7 @@ constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. + The constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. However, the address family of the `sourceAddress` and `groupAddress` parameters must the same. @@ -143,11 +143,11 @@ method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from a single source address. The multicast group address, single source address, and local port to bind to are specified in the constructor. + The method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from a single source address. The multicast group address, single source address, and local port to bind to are specified in the constructor. The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . ]]> @@ -200,7 +200,7 @@ method begins an operation of receiving a UDP packet from the joined multicast group from a single sender. The local port, multicast group, and sender source address are specified in the constructor. The multicast client must also have completed a join to the multicast group. + The method begins an operation of receiving a UDP packet from the joined multicast group from a single sender. The local port, multicast group, and sender source address are specified in the constructor. The multicast client must also have completed a join to the multicast group. The method specified in the `callback` parameter is invoked when a packet has received. @@ -275,7 +275,7 @@ method begins an operation of sending a UDP packet to the source previously specified. + The method begins an operation of sending a UDP packet to the source previously specified. Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. @@ -349,9 +349,9 @@ when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. + Always call before you release your last reference to the . Otherwise, the resources it is using will not be freed until the garbage collector calls the object's method. ]]> @@ -392,9 +392,9 @@ method completes an asynchronous bind to a socket and join operation to a multicast group. + The method completes an asynchronous bind to a socket and join operation to a multicast group. - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. @@ -444,7 +444,7 @@ method completes an asynchronous operation to receive a packet from a single source in a multicast group. + The method completes an asynchronous operation to receive a packet from a single source in a multicast group. If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. @@ -492,7 +492,7 @@ method completes an asynchronous operation to send a packet to single source previously specified. + The method completes an asynchronous operation to send a packet to single source previously specified. If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. @@ -539,7 +539,7 @@ used for multicast receive operations on this instance. Specifically, the `ReceiveBufferSize` property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. + The `ReceiveBufferSize` property gets or sets the size, in bytes, of the receive buffer of the underlying used for multicast receive operations on this instance. Specifically, the `ReceiveBufferSize` property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. The default size of the receive buffer on Windows is 8,192. @@ -586,9 +586,9 @@ ## Remarks The SendBufferSize property gets or sets the size, in bytes, of the send buffer of the underlying used for multicast send operations on this instance. - On Mac OS X, the property controls how many bytes can be in the network stack's waiting-to-be-sent buffer before additional calls to the method start failing. Applications on Mac OS X may need to be concerned with this property if they are sending a large number of UDP packets in a short timeframe. + On Mac OS X, the property controls how many bytes can be in the network stack's waiting-to-be-sent buffer before additional calls to the method start failing. Applications on Mac OS X may need to be concerned with this property if they are sending a large number of UDP packets in a short timeframe. - On Windows, calls to the method will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. + On Windows, calls to the method will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. The default size of the send buffer on Windows is 8,192. diff --git a/xml/System.Net.WebSockets/ClientWebSocket.xml b/xml/System.Net.WebSockets/ClientWebSocket.xml index 6a50156d2ca..a9c77457ed7 100644 --- a/xml/System.Net.WebSockets/ClientWebSocket.xml +++ b/xml/System.Net.WebSockets/ClientWebSocket.xml @@ -403,24 +403,24 @@ Exactly one send and one receive is supported on each method initiates the WebSocket handshake with a remote network destination, and then negotiates the sub-protocol. + The method initiates the WebSocket handshake with a remote network destination, and then negotiates the sub-protocol. For plain WebSocket connections, use the `ws://` scheme in the uri. For secure WebSocket connections over TLS/SSL, use the `wss://` scheme. This operation will not block. The returned object will complete after the connect request on the instance has completed. - + The WebSocket handshake request has default headers for HTTP/1.1 request: - + `Connection: Upgrade` - + `Upgrade: websocket` - + `Sec-WebSocket-Key: [generated key]` - + For HTTP/2 request: - + `:protocol: websocket` - + By default, HTTP/1.1 will be used. To change HTTP version used or enable HTTP version upgrade/downgrade, see option and option. ]]> @@ -676,7 +676,7 @@ Exactly one send and one receive is supported on each object will complete after the receive request on the instance has completed. + This operation will not block. The returned object will complete after the receive request on the instance has completed. Exactly one send and one receive is supported on each object in parallel. Issuing multiple receives at the same time is *not supported* and will result in an *undefined behavior*. You should serialize receive operations via whatever mechanism works best for you, for example, by using a lock or a semaphore. @@ -727,7 +727,7 @@ Exactly one send and one receive is supported on each object will complete after the receive request on the instance has completed. + This operation will not block. The returned object will complete after the receive request on the instance has completed. Exactly one send and one receive is supported on each object in parallel. Issuing multiple receives at the same time is *not supported* and will result in an *undefined behavior*. You should serialize receive operations via whatever mechanism works best for you, for example, by using a lock or a semaphore. diff --git a/xml/System.Net.WebSockets/WebSocket.xml b/xml/System.Net.WebSockets/WebSocket.xml index a6453bebc2f..6cd4c6a3c6f 100644 --- a/xml/System.Net.WebSockets/WebSocket.xml +++ b/xml/System.Net.WebSockets/WebSocket.xml @@ -49,13 +49,13 @@ The WebSocket class allows applications to send and receive data after the WebSocket upgrade has completed. - namespace are supported on Windows 7, Windows Vista SP2, and Windows Server 2008. However, the only public implementations of client and server WebSockets are supported on Windows 8 and Windows Server 2012. The classes and class elements in the namespace that are supported on Windows 7, Windows Vista SP2, and Windows Server 2008 are abstract classes. This allows an application developer to inherit and extend these abstract classes with an actual implementation of client WebSockets. Exactly one send and one receive is supported on each object in parallel. Issuing multiple sends or multiple receives at the same time (for example, without awaiting, or from multiple threads without synchronization) is *not supported* and will result in an *undefined behavior*. Ensure that the previous operation is awaited (or completed) before issuing the next one. Serialize the access via whatever mechanism works best for you, for example, by using a lock or a semaphore. - + ]]> @@ -193,13 +193,13 @@ Exactly one send and one receive is supported on each Closes the WebSocket connection as an asynchronous operation using the close handshake defined in the WebSocket protocol specification, section 7. The task object representing the asynchronous operation. - object will complete after the WebSocket has been closed. - - This method closes the WebSocket connection using the close handshake defined in the [WebSocket protocol specification](https://datatracker.ietf.org/doc/html/rfc6455), section 7. - + object will complete after the WebSocket has been closed. + + This method closes the WebSocket connection using the close handshake defined in the [WebSocket protocol specification](https://datatracker.ietf.org/doc/html/rfc6455), section 7. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -260,11 +260,11 @@ Exactly one send and one receive is supported on each Initiates or completes the close handshake defined in the WebSocket protocol specification, section 7. The task object representing the asynchronous operation. - object will complete after the output on the WebSocket has been closed. - + object will complete after the output on the WebSocket has been closed. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -309,11 +309,11 @@ Exactly one send and one receive is supported on each Indicates the reason why the remote endpoint initiated the close handshake. Returns . - @@ -855,13 +855,13 @@ Exactly one send and one receive is supported on each Receives data from the connection asynchronously. The task object representing the asynchronous operation. The property on the task object returns a object that represents the received data. - object will complete after the data has been received on the . - + object will complete after the data has been received on the . + Exactly one send and one receive is supported on each object in parallel. Issuing multiple receives at the same time is *not supported* and will result in an *undefined behavior*. You should serialize receive operations via whatever mechanism works best for you, for example, by using a lock or a semaphore. - + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -1013,13 +1013,13 @@ Exactly one send and one receive is supported on each Sends data over the connection asynchronously. The task object representing the asynchronous operation. - object will complete after the data has been sent on the . - -Exactly one send and one receive is supported on each object in parallel. Issuing multiple sends at the same time is *not supported* and will result in an *undefined behavior*. You should serialize send operations via whatever mechanism works best for you, for example, by using a lock or a semaphore. - + object will complete after the data has been sent on the . + +Exactly one send and one receive is supported on each object in parallel. Issuing multiple sends at the same time is *not supported* and will result in an *undefined behavior*. You should serialize send operations via whatever mechanism works best for you, for example, by using a lock or a semaphore. + ]]> The cancellation token was canceled. This exception is stored into the returned task. diff --git a/xml/System.Net/AuthenticationManager.xml b/xml/System.Net/AuthenticationManager.xml index 67aea2e5332..fe2ee9e2130 100644 --- a/xml/System.Net/AuthenticationManager.xml +++ b/xml/System.Net/AuthenticationManager.xml @@ -59,11 +59,11 @@ is a static class that manages the authentication modules that an application uses. When a request is made to protected resources, the calls the method to get an instance to use in subsequent requests. + is a static class that manages the authentication modules that an application uses. When a request is made to protected resources, the calls the method to get an instance to use in subsequent requests. - The queries each registered authentication module by calling the method for each module. The first authentication module to return an instance is used to authenticate the request. + The queries each registered authentication module by calling the method for each module. The first authentication module to return an instance is used to authenticate the request. - Modules that provide the basic, digest, negotiate, NTLM, and Kerberos authentication types are registered with the by default. Additional authentication modules that implement the interface can be added using the method. Authentication modules are called in the order in which they were added to the list. + Modules that provide the basic, digest, negotiate, NTLM, and Kerberos authentication types are registered with the by default. Additional authentication modules that implement the interface can be added using the method. Authentication modules are called in the order in which they were added to the list. ## Examples :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet1"::: @@ -138,9 +138,9 @@ method calls the method on each registered authentication module until one of the module responds with an instance. + The method calls the method on each registered authentication module until one of the module responds with an instance. - The first instance returned is used to authenticate the request. If no authentication module can authenticate the request, the method returns `null`. + The first instance returned is used to authenticate the request. If no authentication module can authenticate the request, the method returns `null`. Authentication modules are called in the order in which they are registered with the . @@ -275,14 +275,14 @@ to in your request. + An SPN is a name by which a client uniquely identifies an instance of a service or application on a server for purposes of mutual authentication. Mutual authentication is requested by default, and you can require it by setting to in your request. - When a requires mutual authentication, the SPN for the destination must be supplied by the client. If you know the SPN, you can add it to the before sending the request. If you have not added SPN information to this dictionary, the uses the method to compose the most likely SPN; however, this is a computed value and might be incorrect. If mutual authentication is attempted and fails, you can check the dictionary to determine the computed SPN. No SPN is entered into the dictionary if the authentication protocol does not support mutual authentication. + When a requires mutual authentication, the SPN for the destination must be supplied by the client. If you know the SPN, you can add it to the before sending the request. If you have not added SPN information to this dictionary, the uses the method to compose the most likely SPN; however, this is a computed value and might be incorrect. If mutual authentication is attempted and fails, you can check the dictionary to determine the computed SPN. No SPN is entered into the dictionary if the authentication protocol does not support mutual authentication. - To add an SPN value to this dictionary, use the of the as the key. Internally, the key is truncated to include the , , and the if it is not the default port. + To add an SPN value to this dictionary, use the of the as the key. Internally, the key is truncated to include the , , and the if it is not the default port. > [!NOTE] -> Accessing the methods and properties of the requires unrestricted . +> Accessing the methods and properties of the requires unrestricted . > [!NOTE] > When Kerberos authentication is performed through a proxy, both the proxy and the ultimate host name need to be resolved to an SPN. The proxy name resolution is protected by a timeout. Resolution of the ultimate host name to a SPN requires a DNS lookup, and there is no timeout associated directly with this operation. Therefore synchronous operations may take longer to timeout. To overcome this, add the ultimate host's URI prefix to the SPN cache prior to making requests to it. @@ -292,7 +292,7 @@ ## Examples - The following code example demonstrates displaying the contents of the . + The following code example demonstrates displaying the contents of the . :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/IntranetZoneCredentialPolicy/Overview/websample.cs" id="Snippet5"::: @@ -363,7 +363,7 @@ method returns an Authentication instance and sends the authorization information to the server preemptively instead of waiting for the resource to issue a challenge. This behavior is outlined in section 3.3 of RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). Authentication modules that support preauthentication allow clients to improve server efficiency by avoiding extra round trips caused by authentication challenges. + If the authentication module can preauthenticate the request, the method returns an Authentication instance and sends the authorization information to the server preemptively instead of waiting for the resource to issue a challenge. This behavior is outlined in section 3.3 of RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). Authentication modules that support preauthentication allow clients to improve server efficiency by avoiding extra round trips caused by authentication challenges. Authorization modules that can preauthenticate requests set the property to `true`. @@ -420,7 +420,7 @@ method adds authentication modules to the end of the list of modules called by the method. Authentication modules are called in the order in which they were added to the list. If a module with the same is already registered, this method removes the registered module and adds `authenticationModule` to the end of the list. + The method adds authentication modules to the end of the list of modules called by the method. Authentication modules are called in the order in which they were added to the list. If a module with the same is already registered, this method removes the registered module and adds `authenticationModule` to the end of the list. @@ -479,7 +479,7 @@ property provides an instance that enables the list of registered authentication modules to be read. The method adds modules to the list, and the method removes modules from it. + The property provides an instance that enables the list of registered authentication modules to be read. The method adds modules to the list, and the method removes modules from it. @@ -549,12 +549,12 @@ method removes the specified authentication module from the list of authentication modules called by the method. The module must have been added to the list using the method before it can be removed from the list. + The method removes the specified authentication module from the list of authentication modules called by the method. The module must have been added to the list using the method before it can be removed from the list. ## Examples - The following example uses the method to remove the specified authentication module from the list of registered modules. For a complete example, refer to the class. + The following example uses the method to remove the specified authentication module from the list of registered modules. For a complete example, refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Register/custombasicauthentication.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Register/custombasicauthentication.vb" id="Snippet2"::: @@ -612,12 +612,12 @@ method removes the authentication module with the specified authentication scheme from the list of authentication modules called by the method. The module must have been added to the list using the method before it can be removed from the list. + The method removes the authentication module with the specified authentication scheme from the list of authentication modules called by the method. The module must have been added to the list using the method before it can be removed from the list. ## Examples - The following example uses the method to remove an authentication module with the specified authentication scheme from the list of registered modules. + The following example uses the method to remove an authentication module with the specified authentication scheme from the list of registered modules. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Unregister/authenticationmanager_unregister2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Unregister/authenticationmanager_unregister2.vb" id="Snippet2"::: diff --git a/xml/System.Net/Cookie.xml b/xml/System.Net/Cookie.xml index 24be2ca285f..d5788df8589 100644 --- a/xml/System.Net/Cookie.xml +++ b/xml/System.Net/Cookie.xml @@ -957,7 +957,7 @@ ## Remarks Setting the `Expires` property to makes this a session cookie, which is its default value. - The property of is used to determine if the cookie is set to or . If the property is set to , then is assumed. + The property of is used to determine if the cookie is set to or . If the property is set to , then is assumed. @@ -1584,9 +1584,9 @@ of a must not be `null`. If a `null` value is assigned to this property, it's replaced with an empty string. + The of a must not be `null`. If a `null` value is assigned to this property, it's replaced with an empty string. - Semicolons and commas are reserved characters that cannot be used in the value of this property. Assigning invalid characters to this property doesn't throw an exception; but when you try to add this to a instance with the method, the operation will fail and throw an exception. + Semicolons and commas are reserved characters that cannot be used in the value of this property. Assigning invalid characters to this property doesn't throw an exception; but when you try to add this to a instance with the method, the operation will fail and throw an exception. diff --git a/xml/System.Net/CookieCollection.xml b/xml/System.Net/CookieCollection.xml index e95f9c6cfa6..4b480e9f624 100644 --- a/xml/System.Net/CookieCollection.xml +++ b/xml/System.Net/CookieCollection.xml @@ -157,9 +157,9 @@ |Property|Default| |--------------|-------------| -||`true`| -||0| -||`false`| +||`true`| +||0| +||`false`| ]]> @@ -394,9 +394,9 @@ , and match. -The comparison for and is case-insensitive. -The comparison for is case-sensitive. +The `cookie` is determined to be part of the collection if , and match. +The comparison for and is case-insensitive. +The comparison for is case-sensitive. ]]> @@ -982,11 +982,11 @@ The comparison for is case-sensitive. , and match. +The `cookie` is determined to be part of the collection if , and match. -The comparison for and is case-insensitive. +The comparison for and is case-insensitive. -The comparison for is case-sensitive. +The comparison for is case-sensitive. ]]> @@ -1090,11 +1090,11 @@ The comparison for is case-sensitive. only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. + You should use an only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an . Two enumerators created from the same collection at the same time can produce different snapshots of the collection. - This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Net/CookieContainer.xml b/xml/System.Net/CookieContainer.xml index d15875deb32..3b2bf134099 100644 --- a/xml/System.Net/CookieContainer.xml +++ b/xml/System.Net/CookieContainer.xml @@ -77,7 +77,7 @@ An instance of the class is added to the container based on its originating URI. It is added to an internal associated with the URI. A is retrieved from the container based on the URI as a , or as a string that can be used to submit HTTP WebRequests. - The has three properties that govern the volume of the content of the container: , , and . These values have the default settings of 300, 4096, and 20 respectively. When a is added to the container, these properties are used to determine whether a already contained in the should be discarded to make room for the new one. The keeps track of each addition to ensure that neither the nor the limits are exceeded. If one or both are exceeded, then instances held by the are removed. First, any expired is removed. If further capacity must be recaptured, then the least-recently used is purged. + The has three properties that govern the volume of the content of the container: , , and . These values have the default settings of 300, 4096, and 20 respectively. When a is added to the container, these properties are used to determine whether a already contained in the should be discarded to make room for the new one. The keeps track of each addition to ensure that neither the nor the limits are exceeded. If one or both are exceeded, then instances held by the are removed. First, any expired is removed. If further capacity must be recaptured, then the least-recently used is purged. ## Thread Safety @@ -153,7 +153,7 @@ is used to initialize , is used for , and is used for . + The parameterless constructor initializes all fields to their default values. is used to initialize , is used for , and is used for . ]]> @@ -209,7 +209,7 @@ is initialized to 20, and is initialized to 4096. + is initialized to 20, and is initialized to 4096. ]]> @@ -271,7 +271,7 @@ , , and . + The parameters specify values for , , and . ]]> @@ -348,7 +348,7 @@ property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + If the property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -488,7 +488,7 @@ If the property of a is Netscape, the property of the , if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name. - If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -564,7 +564,7 @@ If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. - If equals , one or more instances is removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used is found and removed from the container. + If equals , one or more instances is removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -637,9 +637,9 @@ equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + If equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. - must be greater than or equal to . + must be greater than or equal to . ]]> @@ -706,7 +706,7 @@ . If equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + The default value of this property is . If equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -981,9 +981,9 @@ returns a string that holds the HTTP cookie header for the instances specified by `uri`. The HTTP header is built by adding a string representation of each associated with `uri`. Note that the exact format of the string depends on the RFC that the conforms to. The strings for all the instances that are associated with `uri` are combined and delimited by semicolons. + returns a string that holds the HTTP cookie header for the instances specified by `uri`. The HTTP header is built by adding a string representation of each associated with `uri`. Note that the exact format of the string depends on the RFC that the conforms to. The strings for all the instances that are associated with `uri` are combined and delimited by semicolons. - This string is not in the correct format for use as the second parameter of the method. + This string is not in the correct format for use as the second parameter of the method. ]]> @@ -1119,7 +1119,7 @@ is less than the current value, any with a length that exceeds the new value will be truncated. + If the new value of is less than the current value, any with a length that exceeds the new value will be truncated. ]]> @@ -1190,7 +1190,7 @@ value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the cleanup only on the collection for this domain. + If the new value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the cleanup only on the collection for this domain. ]]> @@ -1260,7 +1260,7 @@ pulls all the HTTP cookies out of the HTTP cookie header, builds a for each one, and then adds each to the internal that is associated with the URI. The HTTP cookies in the `cookieHeader` string must be delimited by commas. + pulls all the HTTP cookies out of the HTTP cookie header, builds a for each one, and then adds each to the internal that is associated with the URI. The HTTP cookies in the `cookieHeader` string must be delimited by commas. ]]> diff --git a/xml/System.Net/CookieException.xml b/xml/System.Net/CookieException.xml index e79f70f0ff1..5a270264402 100644 --- a/xml/System.Net/CookieException.xml +++ b/xml/System.Net/CookieException.xml @@ -71,18 +71,18 @@ a with length greater than to a . + This exception is thrown if an attempt is made to a with length greater than to a . ### Tips **Make sure the cookie size does not exceed the maximum allowed by the cookie container.** - This exception is thrown when an attempt is made to add a with length greater than to a . The default maximum cookie size is 4096 bytes. + This exception is thrown when an attempt is made to add a with length greater than to a . The default maximum cookie size is 4096 bytes. **When setting the Name property for a cookie, make sure the value is not a null reference or empty string.** The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), carriage return (\r), tab (\t). The dollar sign ($) character cannot be the first character. **When setting the Port property for a cookie, make sure the value is valid and enclosed in double quotes.** - The attribute restricts the ports to which a cookie may be sent. The default value means no restriction. Setting the property to an empty string ("") restricts the port to the one used in the HTTP response. Otherwise the value must be a string in quotation marks that contains port values delineated with commas. + The attribute restricts the ports to which a cookie may be sent. The default value means no restriction. Setting the property to an empty string ("") restricts the port to the one used in the HTTP response. Otherwise the value must be a string in quotation marks that contains port values delineated with commas. **When setting the Value property for a cookie, make sure the value is not null.** The following characters are reserved and cannot be used for this property: semicolon, comma. diff --git a/xml/System.Net/CredentialCache.xml b/xml/System.Net/CredentialCache.xml index d449874226c..44d678643d0 100644 --- a/xml/System.Net/CredentialCache.xml +++ b/xml/System.Net/CredentialCache.xml @@ -74,7 +74,7 @@ class stores credentials for multiple Internet resources. Applications that need to access multiple resources can store the credentials for those resources in a instance that then provides the proper set of credentials to the Internet resource when required. When the method is called, it compares the Uniform Resource Identifier (URI) and authentication type provided with those stored in the cache and returns the first set of credentials that match. + The class stores credentials for multiple Internet resources. Applications that need to access multiple resources can store the credentials for those resources in a instance that then provides the proper set of credentials to the Internet resource when required. When the method is called, it compares the Uniform Resource Identifier (URI) and authentication type provided with those stored in the cache and returns the first set of credentials that match. The property contains the system credentials of the current security context. For client applications, these represent the user name, password, and domain of the user who is currently logged in. For ASP.NET applications, the default credentials are the user credentials of the logged-in user or the user being impersonated. @@ -210,7 +210,7 @@ method places a instance for use with protocols other than SMTP into the . The cache stores credentials in the order in which they are added to it. When the method is called, it returns the proper matching instance. + The method places a instance for use with protocols other than SMTP into the . The cache stores credentials in the order in which they are added to it. When the method is called, it returns the proper matching instance. ## Examples The following code example initializes a with multiple security credentials and uses those credentials with a . @@ -282,7 +282,7 @@ instance for use with SMTP into the . The cache stores credentials in the order in which they are added to it. When the method is called, it returns a instance that is selected by matching the `host`, `port`, and `authenticationType`. The comparison is done case-insensitively. + This method places a instance for use with SMTP into the . The cache stores credentials in the order in which they are added to it. When the method is called, it returns a instance that is selected by matching the `host`, `port`, and `authenticationType`. The comparison is done case-insensitively. The supported values for `authenticationType` are "NTLM", "Digest", "Kerberos", and "Negotiate". @@ -355,12 +355,12 @@ ## Remarks The property applies only to NTLM, negotiate, and Kerberos-based authentication. - represents the system credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default credentials are the user credentials of the logged-in user, or the user being impersonated. + represents the system credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default credentials are the user credentials of the logged-in user, or the user being impersonated. To get the credentials as a instance, use the property. > [!NOTE] -> The instance returned by cannot be used to view the user name, password, or domain of the current security context. +> The instance returned by cannot be used to view the user name, password, or domain of the current security context. ## Examples The following code example uses the property to get the system credentials of the application. @@ -418,7 +418,7 @@ ## Remarks The credentials returned by the property is applicable only for NTLM, negotiate, and Kerberos-based authentication. - The credentials returned by represents the authentication credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default network credentials are the user credentials of the logged-in user, or the user being impersonated. + The credentials returned by represents the authentication credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default network credentials are the user credentials of the logged-in user, or the user being impersonated. ]]> @@ -490,9 +490,9 @@ method searches the and returns the instance for the specified URI and authorization type. If the contains no matching instance, `null` is returned. + The method searches the and returns the instance for the specified URI and authorization type. If the contains no matching instance, `null` is returned. - uses the longest matching URI prefix in the cache to determine which set of credentials to return for an authorization type. The following table shows examples. + uses the longest matching URI prefix in the cache to determine which set of credentials to return for an authorization type. The following table shows examples. |URI Prefix|Matches| |----------------|-------------| @@ -501,7 +501,7 @@ |`http://www.contoso.com/`|Requests for all resources at `www.contoso.com`, except those in the `portal` path.| ## Examples - The following code example uses the method to return the instance associated with the specified URI and authentication type. + The following code example uses the method to return the instance associated with the specified URI and authentication type. :::code language="csharp" source="~/snippets/csharp/System.Net/CredentialCache/GetCredential/credentialcache_getcredential.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/CredentialCache/GetCredential/credentialcache_getcredential.vb" id="Snippet1"::: @@ -568,7 +568,7 @@ and returns the instance for the specified host, port, and authorization type. The `host`, `port`, and `authenticationType` values passed to this method are case-insensitively compared to the values specified when the credential was added to the using the methods. + This method searches the and returns the instance for the specified host, port, and authorization type. The `host`, `port`, and `authenticationType` values passed to this method are case-insensitively compared to the values specified when the credential was added to the using the methods. The supported values for `authenticationType` are "NTLM", "Digest", "Kerberos", and "Negotiate". @@ -639,7 +639,7 @@ method to return an enumerator that can iterate through the instance. + The following code example uses the method to return an enumerator that can iterate through the instance. :::code language="csharp" source="~/snippets/csharp/System.Net/CredentialCache/GetEnumerator/credentialcache_getenumerator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/CredentialCache/GetEnumerator/credentialcache_getenumerator.vb" id="Snippet1"::: @@ -710,7 +710,7 @@ instance from the if the specified URI prefix and authentication protocol match those associated with the credential. Multiple calls to the method for the same have no effect. + This method removes a instance from the if the specified URI prefix and authentication protocol match those associated with the credential. Multiple calls to the method for the same have no effect. If `authType` is `null` or `uriPrefix` is `null`, or no matching credential is found in the cache, this method does nothing. @@ -776,7 +776,7 @@ instance from the if the specified host, port, and authentication protocol match those associated with the credential. Multiple calls to the method for the same have no effect. + This method removes a instance from the if the specified host, port, and authentication protocol match those associated with the credential. Multiple calls to the method for the same have no effect. If `authenticationType` is `null` or `uriPrefix` is `null`, or no matching credential is found in the cache, this method does nothing. diff --git a/xml/System.Net/Dns.xml b/xml/System.Net/Dns.xml index 33c9ed49da6..1ab72a01b9a 100644 --- a/xml/System.Net/Dns.xml +++ b/xml/System.Net/Dns.xml @@ -141,16 +141,16 @@ method asynchronously queries a DNS server for the IP addresses that are associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. + The method asynchronously queries a DNS server for the IP addresses that are associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) @@ -244,9 +244,9 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -336,20 +336,20 @@ method asynchronously queries a DNS server for the IP addresses and aliases associated with an IP address. + The method asynchronously queries a DNS server for the IP addresses and aliases associated with an IP address. **Note** This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously) ## Examples - The following code example uses the method to resolve an IP address to an instance. + The following code example uses the method to resolve an IP address to an instance. :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.vb" id="Snippet2"::: @@ -428,20 +428,20 @@ method queries a DNS server for the IP address that is associated with a host name or IP address. + The method queries a DNS server for the IP address that is associated with a host name or IP address. **Note** This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example uses the method to resolve an IP address to an instance. + The following code example uses the method to resolve an IP address to an instance. :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.vb" id="Snippet2"::: @@ -536,9 +536,9 @@ operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `requestCallback` delegate. - This method does not block until the operation is complete. To block until the operation is complete, use the method. + This method does not block until the operation is complete. To block until the operation is complete, use the method. For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -599,7 +599,7 @@ method queries a DNS server for the IP addresses associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. + The method queries a DNS server for the IP addresses associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. @@ -673,7 +673,7 @@ ## Remarks This method blocks until the operation is complete. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. @@ -737,7 +737,7 @@ The property of the instance returned is not populated by this method and will always be empty. - To perform this operation synchronously, use a method. + To perform this operation synchronously, use a method. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -811,9 +811,9 @@ ## Remarks This method blocks until the operation is complete. - If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. - To perform this operation synchronously, use the method. + To perform this operation synchronously, use the method. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -871,11 +871,11 @@ method queries the DNS subsystem for the IP addresses associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. + The method queries the DNS subsystem for the IP addresses associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. - IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results were available for the `hostNameOrAddress` parameter. + IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results were available for the `hostNameOrAddress` parameter. This method is implemented using the underlying operating system's name resolution APIs (such as the Win32 API getaddrinfo on Windows, and equivalent APIs on other platforms). If a host is described in the `hosts` file, the IP address or addresses there will be returned without querying the DNS server. @@ -885,7 +885,7 @@ ## Examples - The following code example uses the method to resolve an IP address to an array of type . + The following code example uses the method to resolve an IP address to an array of type . :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.vb" id="Snippet3"::: @@ -981,7 +981,7 @@ object will complete after the `hostNameOrAddress` has been resolved. + This operation will not block. The returned object will complete after the `hostNameOrAddress` has been resolved. This method queries a DNS server for the IP addresses associated with a host name. If `hostNameOrAddress` is an IP address, this address is returned without querying the DNS server. @@ -1287,9 +1287,9 @@ method queries the Internet DNS server for host information. If you pass an empty string as the host name, this method retrieves the standard host name for the local computer. + The method queries the Internet DNS server for host information. If you pass an empty string as the host name, this method retrieves the standard host name for the local computer. - For asynchronous access to DNS information, use the and methods. + For asynchronous access to DNS information, use the and methods. If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. @@ -1360,9 +1360,9 @@ method queries a DNS server for the IP addresses and aliases associated with an IP address. + The method queries a DNS server for the IP addresses and aliases associated with an IP address. - IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results were available for the `address` parameter. + IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results were available for the `address` parameter. The property of the instance returned is not populated by this method and will always be empty. @@ -1370,7 +1370,7 @@ > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example uses the method to resolve an IP address to an instance. + The following code example uses the method to resolve an IP address to an instance. :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.vb" id="Snippet4"::: @@ -1430,7 +1430,7 @@ method queries a DNS server for the IP address that is associated with a host name or IP address. + The method queries a DNS server for the IP address that is associated with a host name or IP address. If an empty string is passed as the `hostNameOrAddress` argument, then this method returns the IPv4 and IPv6 addresses of the local host. @@ -1438,7 +1438,7 @@ The exception is also returned if the `hostNameOrAddress` parameter contains or . - The method assumes that if an IP literal string is passed in the `hostNameOrAddress` parameter that the application wants an instance returned with all of the properties set. These properties include the , , and . As a result, the implementation of the method exhibits the following behavior when an IP string literal is passed: + The method assumes that if an IP literal string is passed in the `hostNameOrAddress` parameter that the application wants an instance returned with all of the properties set. These properties include the , , and . As a result, the implementation of the method exhibits the following behavior when an IP string literal is passed: 1. The method tries to parse the address. If the `hostNameOrAddress` parameter contains a legal IP string literal, then the first phase succeeds. @@ -1450,9 +1450,9 @@ For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. - The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. + The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. - IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `hostNameOrAddress`.parameter. + IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `hostNameOrAddress`.parameter. The property of the instance returned is not populated by this method and will always be empty. @@ -1462,7 +1462,7 @@ ## Examples - The following example uses the method to resolve an IP address to an instance. + The following example uses the method to resolve an IP address to an instance. :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/BeginGetHostEntry/dnsnewmethods.vb" id="Snippet1"::: @@ -1566,7 +1566,7 @@ object will complete after the `address` has been resolved. + This operation will not block. The returned object will complete after the `address` has been resolved. This method queries a DNS server for the IP addresses and aliases associated with an IP address. @@ -1634,7 +1634,7 @@ object will complete after the `hostNameOrAddress` has been resolved. + This operation will not block. The returned object will complete after the `hostNameOrAddress` has been resolved. This method queries a DNS server for the IP address that is associated with a host name or IP address. @@ -1644,7 +1644,7 @@ The exception is also returned if the `hostNameOrAddress` parameter contains or . - This method assumes that if an IP literal string is passed in the `hostNameOrAddress` parameter that the application wants an instance returned with all of the properties set. These properties include the , , and . As a result, the implementation of this method exhibits the following behavior when an IP string literal is passed: + This method assumes that if an IP literal string is passed in the `hostNameOrAddress` parameter that the application wants an instance returned with all of the properties set. These properties include the , , and . As a result, the implementation of this method exhibits the following behavior when an IP string literal is passed: 1. The method tries to parse the address. If the `hostNameOrAddress` parameter contains a legal IP string literal, then the first phase succeeds. @@ -1656,7 +1656,7 @@ For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. - The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. + The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. IPv6 addresses are filtered from the results of this method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `hostNameOrAddress`.parameter. @@ -1795,7 +1795,7 @@ method to obtain the host name of the local computer. + The following example uses the method to obtain the host name of the local computer. :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/GetHostName/dns_gethostname.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/GetHostName/dns_gethostname.vb" id="Snippet1"::: @@ -1866,7 +1866,7 @@ method queries a DNS server for the IP address associated with a host name or IP address. + The method queries a DNS server for the IP address associated with a host name or IP address. When `hostName` is a DNS-style host name associated with multiple IP addresses, only the first IP address that resolves to that host name is returned. diff --git a/xml/System.Net/DnsEndPoint.xml b/xml/System.Net/DnsEndPoint.xml index 68225fd0428..599f5f5dea0 100644 --- a/xml/System.Net/DnsEndPoint.xml +++ b/xml/System.Net/DnsEndPoint.xml @@ -127,9 +127,9 @@ constructor can be used to initialize a class using either a host name or a string that represents an IP address and a port. This constructor sets the property to . + The constructor can be used to initialize a class using either a host name or a string that represents an IP address and a port. This constructor sets the property to . - When using this constructor with a host name rather than a string representation of an IP address, the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). + When using this constructor with a host name rather than a string representation of an IP address, the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). ]]> @@ -192,9 +192,9 @@ constructor can be used to initialize a class using either a host name or a string that represents an IP address, a port, and an address family. + The constructor can be used to initialize a class using either a host name or a string that represents an IP address, a port, and an address family. - When using the constructor with a host name rather than a string representation of an IP address, the address family restricts DNS resolution to prefer addresses of the specified address family value. When using the constructor with the address family specified as , the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). + When using the constructor with a host name rather than a string representation of an IP address, the address family restricts DNS resolution to prefer addresses of the specified address family value. When using the constructor with the address family specified as , the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). ]]> @@ -327,7 +327,7 @@ method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same endpoint. + The method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same endpoint. ]]> @@ -379,7 +379,7 @@ method returns a hash code of the . This value can be used as a key in hash tables. + The method returns a hash code of the . This value can be used as a key in hash tables. ]]> @@ -538,7 +538,7 @@ method returns a string that contains the address family, the host name or IP address string, and the port number. + The method returns a string that contains the address family, the host name or IP address string, and the port number. ]]> diff --git a/xml/System.Net/DnsPermission.xml b/xml/System.Net/DnsPermission.xml index e6706fe00b4..a822877826b 100644 --- a/xml/System.Net/DnsPermission.xml +++ b/xml/System.Net/DnsPermission.xml @@ -188,9 +188,9 @@ method reconstructs a instance from an XML encoding defined by the class. + The method reconstructs a instance from an XML encoding defined by the class. - Use the method to XML-encode the instance, including state information. + Use the method to XML-encode the instance, including state information. ]]> @@ -241,7 +241,7 @@ method returns a instance that allows the access defined by both the current instance and the specified instance. Any demand must pass both permissions to pass their intersection. + The method returns a instance that allows the access defined by both the current instance and the specified instance. Any demand must pass both permissions to pass their intersection. ]]> @@ -292,7 +292,7 @@ ## Remarks The current instance is a subset of the specified instance if the current instance specifies a set of operations that is wholly contained by the specified instance. - If the method returns `true`, the current instance allows no more access to DNS servers than does the specified instance. + If the method returns `true`, the current instance allows no more access to DNS servers than does the specified instance. ]]> @@ -377,9 +377,9 @@ method creates a instance to XML-encode a representation of the instance, including state information. + The method creates a instance to XML-encode a representation of the instance, including state information. - Use the method to restore the state information from a instance. + Use the method to restore the state information from a instance. ]]> @@ -425,7 +425,7 @@ method returns a instance that allows the access defined by either the current instance or the specified instance. Any demand that passes either permission passes their union. + The method returns a instance that allows the access defined by either the current instance or the specified instance. Any demand that passes either permission passes their union. ]]> diff --git a/xml/System.Net/DnsPermissionAttribute.xml b/xml/System.Net/DnsPermissionAttribute.xml index 9814ef7715a..eb7c0426718 100644 --- a/xml/System.Net/DnsPermissionAttribute.xml +++ b/xml/System.Net/DnsPermissionAttribute.xml @@ -157,7 +157,7 @@ ## Remarks The `CreatePermission` method is called by the security system, not by application code. - The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system then accesses the information at run time and calls . The system uses the returned to enforce the specified security requirements. + The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system then accesses the information at run time and calls . The system uses the returned to enforce the specified security requirements. ]]> diff --git a/xml/System.Net/DownloadDataCompletedEventArgs.xml b/xml/System.Net/DownloadDataCompletedEventArgs.xml index 18a7410d705..708c9b50b71 100644 --- a/xml/System.Net/DownloadDataCompletedEventArgs.xml +++ b/xml/System.Net/DownloadDataCompletedEventArgs.xml @@ -115,7 +115,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/DownloadProgressChangedEventHandler.xml b/xml/System.Net/DownloadProgressChangedEventHandler.xml index 94be34c0fa6..6d000422ffb 100644 --- a/xml/System.Net/DownloadProgressChangedEventHandler.xml +++ b/xml/System.Net/DownloadProgressChangedEventHandler.xml @@ -63,7 +63,7 @@ When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). > [!NOTE] -> If the server does not send the size of the downloaded file (such as in the case of a passive FTP connection), may always be zero. +> If the server does not send the size of the downloaded file (such as in the case of a passive FTP connection), may always be zero. ## Examples diff --git a/xml/System.Net/DownloadStringCompletedEventArgs.xml b/xml/System.Net/DownloadStringCompletedEventArgs.xml index 3b9371181e7..90942815bbe 100644 --- a/xml/System.Net/DownloadStringCompletedEventArgs.xml +++ b/xml/System.Net/DownloadStringCompletedEventArgs.xml @@ -122,7 +122,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/EndpointPermission.xml b/xml/System.Net/EndpointPermission.xml index a57ac2d8008..04fd2cb9fd0 100644 --- a/xml/System.Net/EndpointPermission.xml +++ b/xml/System.Net/EndpointPermission.xml @@ -246,7 +246,7 @@ method returns a string that represents the contents for the instance. The string is in the form # # . + The method returns a string that represents the contents for the instance. The string is in the form # # . ]]> diff --git a/xml/System.Net/FileWebRequest.xml b/xml/System.Net/FileWebRequest.xml index cf783bb96f7..2aca71599db 100644 --- a/xml/System.Net/FileWebRequest.xml +++ b/xml/System.Net/FileWebRequest.xml @@ -69,11 +69,11 @@ ## Remarks The class implements the `abstract` base class for Uniform Resource Identifiers (URIs) that use the `file://` scheme to request local files. - Do not use the constructor. Use the method to initialize new instances of the class. If the URI scheme is `file://`, the method returns a object. + Do not use the constructor. Use the method to initialize new instances of the class. If the URI scheme is `file://`, the method returns a object. - The method makes a synchronous request for the file specified in the property and returns a object that contains the response. You can make an asynchronous request for the file using the and methods. + The method makes a synchronous request for the file specified in the property and returns a object that contains the response. You can make an asynchronous request for the file using the and methods. - When you want to write data to a file, the method returns a instance to write to. The and methods provide asynchronous access to the write data stream. + When you want to write data to a file, the method returns a instance to write to. The and methods provide asynchronous access to the write data stream. The class relies on the class for error handling and code access security. @@ -202,7 +202,7 @@ method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . + The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -266,12 +266,12 @@ method starts an asynchronous request for a stream used to send data to a file system resource. The callback method that implements the delegate uses the method to return the request stream. + The method starts an asynchronous request for a stream used to send data to a file system resource. The callback method that implements the delegate uses the method to return the request stream. ## Examples - The following code example uses to make an asynchronous request for a object. + The following code example uses to make an asynchronous request for a object. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/BeginGetRequestStream/filewebrequest_reqbeginend.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/BeginGetRequestStream/filewebrequest_reqbeginend.vb" id="Snippet2"::: @@ -343,12 +343,12 @@ delegate uses the method to return the actual . + The asynchronous callback method that implements the delegate uses the method to return the actual . ## Examples - The following code example uses the method to asynchronously access a file system resource. + The following code example uses the method to asynchronously access a file system resource. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/BeginGetResponse/filewebrequest_resbeginend.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/BeginGetResponse/filewebrequest_resbeginend.vb" id="Snippet2"::: @@ -653,15 +653,15 @@ method completes an asynchronous stream request that was started by the method. + The method completes an asynchronous stream request that was started by the method. > [!NOTE] -> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by the method after calling the method. +> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by the method after calling the method. ## Examples - The following example uses the method to end the asynchronous request for a object. + The following example uses the method to end the asynchronous request for a object. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/BeginGetRequestStream/filewebrequest_reqbeginend.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/BeginGetRequestStream/filewebrequest_reqbeginend.vb" id="Snippet2"::: @@ -722,12 +722,12 @@ method completes an asynchronous request for a file system resource that was started with the method. + The method completes an asynchronous request for a file system resource that was started with the method. ## Examples - The following code example uses the method to end an asynchronous request for a file system resource. + The following code example uses the method to end an asynchronous request for a file system resource. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/BeginGetResponse/filewebrequest_resbeginend.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/BeginGetResponse/filewebrequest_resbeginend.vb" id="Snippet2"::: @@ -844,12 +844,12 @@ method provides synchronous access to the . For asynchronous access, use the and methods. + The method provides synchronous access to the . For asynchronous access, use the and methods. ## Examples - The following code example uses the method to obtain a stream instance used to write to the file. Refer to the complete example in the class. + The following code example uses the method to obtain a stream instance used to write to the file. Refer to the complete example in the class. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/Overview/getrequeststream.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/Overview/getrequeststream.vb" id="Snippet5"::: @@ -956,14 +956,14 @@ The stream already received a response previous to your request. method returns a object that contains the response from the file system resource. + The method returns a object that contains the response from the file system resource. - The method provides synchronous access to the . For asynchronous access, use the and methods. + The method provides synchronous access to the . For asynchronous access, use the and methods. ## Examples - The following code example uses the method to return a file system request response. + The following code example uses the method to return a file system request response. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/GetResponse/getresponse.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/GetResponse/getresponse.vb" id="Snippet1"::: @@ -1430,7 +1430,7 @@ This method stores in the task it returns all non-usage exceptions that the meth to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. @@ -1487,7 +1487,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> diff --git a/xml/System.Net/FileWebResponse.xml b/xml/System.Net/FileWebResponse.xml index aa9bea7f538..3e518707bca 100644 --- a/xml/System.Net/FileWebResponse.xml +++ b/xml/System.Net/FileWebResponse.xml @@ -77,9 +77,9 @@ ## Remarks The class implements the `abstract` base class to return file system resources for the class. - Client applications do not create instances directly; instead, they are created by calling the method on a instance. + Client applications do not create instances directly; instead, they are created by calling the method on a instance. - The method returns a instance that provides read-only access to a file system resource. + The method returns a instance that provides read-only access to a file system resource. The class relies on the class for error handling and code access security. @@ -200,15 +200,15 @@ method cleans up the resources used by a and closes the response stream by calling the method. + The method cleans up the resources used by a and closes the response stream by calling the method. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. You can closes the response stream by calling either or +> The response stream must be closed to avoid running out of system resources. You can closes the response stream by calling either or ## Examples - The following example uses the method to close the response stream. + The following example uses the method to close the response stream. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/Close/filewebresponse_close.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/Close/filewebresponse_close.vb" id="Snippet1"::: @@ -317,7 +317,7 @@ property contains the content type of the file system resource. The value of is always "binary/octet-stream". + The property contains the content type of the file system resource. The value of is always "binary/octet-stream". @@ -465,15 +465,15 @@ method returns the data stream from the file system resource. + The method returns the data stream from the file system resource. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or +> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or ## Examples - The following example uses the method to return the data stream from the file system resource. + The following example uses the method to return the data stream from the file system resource. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/GetResponseStream/filewebresponse_getresponsestream.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/GetResponseStream/filewebresponse_getresponsestream.vb" id="Snippet1"::: @@ -525,7 +525,7 @@ property contains two name/value pairs, one for content length and one for content type, both of which are also exposed as properties, and . + The property contains two name/value pairs, one for content length and one for content type, both of which are also exposed as properties, and . @@ -587,7 +587,7 @@ ## Examples - The following example uses the to retrieve the URI of the file system resource that provided the response. + The following example uses the to retrieve the URI of the file system resource that provided the response. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/ResponseUri/filewebresponse_responseuri.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/ResponseUri/filewebresponse_responseuri.vb" id="Snippet1"::: diff --git a/xml/System.Net/FtpWebRequest.xml b/xml/System.Net/FtpWebRequest.xml index ef3da3ed733..f6a03f44e13 100644 --- a/xml/System.Net/FtpWebRequest.xml +++ b/xml/System.Net/FtpWebRequest.xml @@ -58,26 +58,26 @@ > [!IMPORTANT] > We don't recommend that you use the `FtpWebRequest` class for new development. For more information and alternatives to `FtpWebRequest`, see [WebRequest shouldn't be used](https://github.com/dotnet/platform-compat/blob/master/docs/DE0003.md) on GitHub. - To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. + To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. - You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. + You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. > [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. You must have to access the FTP resource; otherwise, a exception is thrown. - Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . + Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . - When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request. + When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request. - Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server. + Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server. You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to . - When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see . + When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see . If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported. @@ -231,9 +231,9 @@ method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by this method. + You must complete the asynchronous operation by calling the method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by this method. - This method does not block while waiting for the stream. To block, call in place of this method. + This method does not block while waiting for the stream. To block, call in place of this method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). @@ -318,18 +318,18 @@ method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by the method. + You must complete the asynchronous operation by calling the method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by the method. If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. - does not block while waiting for the response from the server. To block, call the method in place of . + does not block while waiting for the response from the server. To block, call the method in place of . For more information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). > [!NOTE] -> If a is thrown, use the and properties of the exception to determine the response from the server. +> If a is thrown, use the and properties of the exception to determine the response from the server. @@ -401,10 +401,10 @@ . + Client certificates are used to authenticate the client during the initial SSL connection negotiation. For more information, see . > [!NOTE] -> The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. +> The .NET Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the .NET Framework uses the first element of (if there is one), or tries to reuse an anonymous session if is empty. ]]> @@ -470,7 +470,7 @@ Using connection groups can improve performance because this allows all of the requests for a user to reuse the connection authenticated with the user's credentials. - Changing the property after calling the , , , or method causes an exception. + Changing the property after calling the , , , or method causes an exception. @@ -543,7 +543,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -599,9 +599,9 @@ ## Remarks Set the property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero. - Setting causes the to send a restart (`REST`) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server. + Setting causes the to send a restart (`REST`) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server. - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. @@ -665,7 +665,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -726,7 +726,7 @@ > [!CAUTION] > Credentials information is not encrypted when transmitted to the server unless the property is set to `true`. - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. @@ -805,7 +805,7 @@ ||If a cached resource exists, it is deleted. The resource is downloaded from the server and is returned to the caller.| > [!NOTE] -> Setting overrides any configuration setting. +> Setting overrides any configuration setting. ]]> @@ -864,7 +864,7 @@ ## Remarks > [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. The `"AUTH TLS"` command is sent to the server to request an encrypted session. If the server does not recognize this command, you receive a exception. @@ -932,9 +932,9 @@ method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . + If the operation has not completed, the method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . - In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. + In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1007,9 +1007,9 @@ method is called, blocks until the operation completes. To prevent blocking, check the property before calling . + If the operation has not completed at the time the method is called, blocks until the operation completes. To prevent blocking, check the property before calling . - In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. + In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1084,11 +1084,11 @@ method. After writing the data to the stream, you must close the stream prior to sending the request. + Set the request properties before calling the method. After writing the data to the stream, you must close the stream prior to sending the request. If you have not set the property to or , you cannot get the stream. - blocks while waiting for the stream. To prevent this, call the method in place of . + blocks while waiting for the stream. To prevent this, call the method in place of . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1166,21 +1166,21 @@ ## Remarks To access the FTP-specific properties, you must cast the object returned by this method to . - causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of . + causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of . If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy. - If a is thrown, use the and properties of the exception to determine the response from the server. + If a is thrown, use the and properties of the exception to determine the response from the server. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). > [!NOTE] -> Multiple calls to return the same response object; the request is not reissued. +> Multiple calls to return the same response object; the request is not reissued. ## Examples - The following code example demonstrates copying a file to a request's data stream and sending a request to append data to a file to the server. The example calls to send the request and block until the response is returned by the server. + The following code example demonstrates copying a file to a request's data stream and sending a request to append data to a file to the server. The example calls to send the request and block until the response is returned by the server. :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet3"::: @@ -1257,7 +1257,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -1312,9 +1312,9 @@ property is set to `false`, the control connection is closed when you call the method. + When the property is set to `false`, the control connection is closed when you call the method. - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. @@ -1382,13 +1382,13 @@ property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. + The property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. - When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream. + When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream. The credentials supplied for the object must have permission to perform the specified method. If not, the FTP command fails. - To determine the success or failure of a command, check the and properties. + To determine the success or failure of a command, check the and properties. @@ -1580,9 +1580,9 @@ The following code example displays this property value. is used when writing to the stream returned by the method or reading from the stream returned by the method. + The is used when writing to the stream returned by the method or reading from the stream returned by the method. - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . + Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . To specify the amount of time to wait for the request to complete, use the property. @@ -1694,7 +1694,7 @@ The following code example displays this property value. property is the URI specified when the method was called to obtain this instance. + The value of the property is the URI specified when the method was called to obtain this instance. @@ -1830,11 +1830,11 @@ The following code example displays this property value. ## Remarks To specify an infinite value, set the property to (-1). This is the default value. - is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . + is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a time-out on your request. @@ -1906,7 +1906,7 @@ The following code example displays this property value. ## Remarks If you are sending binary data, such as an image, set this property to `true`. If you are sending text, set the property to `false`. Specifying `true` causes the to send a `"TYPE I"` command to the server. Specifying `false` causes the to send a `"Type A"` command to the server. FTP servers can ignore these commands. - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. @@ -1968,7 +1968,7 @@ The following code example displays this property value. property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -2026,11 +2026,11 @@ The following code example displays this property value. ## Remarks Setting the property to `true` sends the "`PASV"` command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command. - For a description of the behaviors that are specified using , see [RFC 959: "File Transfer Protocol", Section 3.2: "Establishing Data Connections" and Section 4.1.2: "Transfer Parameter Commands"](https://www.ietf.org/rfc/rfc959.txt). + For a description of the behaviors that are specified using , see [RFC 959: "File Transfer Protocol", Section 3.2: "Establishing Data Connections" and Section 4.1.2: "Transfer Parameter Commands"](https://www.ietf.org/rfc/rfc959.txt). - Changing after calling the , , , or method causes an exception. + Changing after calling the , , , or method causes an exception. - If is set to `true`, the FTP server may not send the size of the file, and download progress can always be zero. If is set to `false`, a firewall can raise an alert and block the file download. + If is set to `true`, the FTP server may not send the size of the file, and download progress can always be zero. If is set to `false`, a firewall can raise an alert and block the file download. diff --git a/xml/System.Net/FtpWebResponse.xml b/xml/System.Net/FtpWebResponse.xml index 7ce89b07059..690d8b1de7b 100644 --- a/xml/System.Net/FtpWebResponse.xml +++ b/xml/System.Net/FtpWebResponse.xml @@ -61,11 +61,11 @@ are obtained by calling the method. The returned object must be cast to an . When your application no longer needs the object, call the method to free the resources held by the . + Instances of are obtained by calling the method. The returned object must be cast to an . When your application no longer needs the object, call the method to free the resources held by the . The property contains the status code returned by the server, and the property returns the status code and a message that describes the status. The values returned by these properties change as the messages are returned by the server. - Any data returned by the request, such as the list of file names returned for a request, is available in the stream returned by the method. The length of the stream data can be obtained from the property. + Any data returned by the request, such as the list of file names returned for a request, is available in the stream returned by the method. The length of the stream data can be obtained from the property. @@ -189,7 +189,7 @@ method closes the data stream returned by the method if the property is `false`. During the close, data might be sent to the server on the control connection. + The method closes the data stream returned by the method if the property is `false`. During the close, data might be sent to the server on the control connection. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -253,9 +253,9 @@ property contains the number of bytes in the stream. returns −1 if no data was returned in the response or if the server did not send content length information. The return value is greater than or equal to zero if data was or should have been returned. For example, for requests that use the field, the property always returns −1. For requests that use the method, the property is always zero. For requests that use the method, the property is greater than zero if the downloaded file contained data and is zero if it was empty. + When a response stream is returned by the FTP server, the property contains the number of bytes in the stream. returns −1 if no data was returned in the response or if the server did not send content length information. The return value is greater than or equal to zero if data was or should have been returned. For example, for requests that use the field, the property always returns −1. For requests that use the method, the property is always zero. For requests that use the method, the property is greater than zero if the downloaded file contained data and is zero if it was empty. - For requests that use the method, returns the size of the specified file on the server. + For requests that use the method, returns the size of the specified file on the server. @@ -551,7 +551,7 @@ This property is provided only for compatibility with other implementations of t property returns the data requested by the method. For requests sent using any other method, returns . + The property returns the data requested by the method. For requests sent using any other method, returns . @@ -620,7 +620,7 @@ This property is provided only for compatibility with other implementations of t ## Remarks Because of server- and resource-specific behaviors, such as redirection, the value returned by the property is not always the same as the value returned by the property. - For requests that use the method, returns the name of the file on the server. + For requests that use the method, returns the name of the file on the server. @@ -681,7 +681,7 @@ This property is provided only for compatibility with other implementations of t property is included in the property. When you are downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. + The value returned by the property is included in the property. When you are downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. @@ -743,7 +743,7 @@ This property is provided only for compatibility with other implementations of t property includes the 3-digit property value. When downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. + The text returned by the property includes the 3-digit property value. When downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. diff --git a/xml/System.Net/GlobalProxySelection.xml b/xml/System.Net/GlobalProxySelection.xml index fba45dacd01..ee54b8bd572 100644 --- a/xml/System.Net/GlobalProxySelection.xml +++ b/xml/System.Net/GlobalProxySelection.xml @@ -67,7 +67,7 @@ stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. + The stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. The proxy settings stored in are used by any derived objects that support proxies and have their property value set to `null` (the default). Proxies are currently supported by , , and . @@ -167,7 +167,7 @@ ## Remarks -The method returns a blank instance to indicate that no proxy is used to access an Internet resource. +The method returns a blank instance to indicate that no proxy is used to access an Internet resource. Instead of calling the `GetEmptyWebProxy` method, you can assign `null` to members such as the property, which specifies the proxy that communicates with remote servers on behalf of the object. diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index 3b732f08766..fcf23d338f7 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -103,7 +103,7 @@ method. + Before using the instance returned by this constructor, you must invoke its method. @@ -230,11 +230,11 @@ uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request. + The uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request. You can interrogate the identity of a successfully authenticated client by using the property. - If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation. + If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation. > [!NOTE] > To set this property to enable Digest, NTLM, or Negotiate requires the , . @@ -305,9 +305,9 @@ > [!NOTE] > If you want the same authentication protocol to be used for all requests handled by a particular instance of , you do not need to set this property. To specify a protocol to be used for all client requests, use the property. - If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. + If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. - The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property). + The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property). > [!NOTE] > To set this property to enable Digest, NTLM, or Negotiate requires the , . @@ -385,18 +385,18 @@ method begins an asynchronous (non-blocking) call to receive incoming client requests. Before calling this method, you must call the method and add at least one Uniform Resource Identifier (URI) prefix to listen for by adding the URI strings to the returned by the property. + The method begins an asynchronous (non-blocking) call to receive incoming client requests. Before calling this method, you must call the method and add at least one Uniform Resource Identifier (URI) prefix to listen for by adding the URI strings to the returned by the property. - The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. + The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the `callback` delegate. - This method does not block while the operation completes. To get an incoming request and block until the operation completes, call the method. + This method does not block while the operation completes. To get an incoming request and block until the operation completes, call the method. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example demonstrates using the method to specify a callback method that will handle incoming client requests. + The following code example demonstrates using the method to specify a callback method that will handle incoming client requests. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet12"::: @@ -458,7 +458,7 @@ object. To temporarily pause an object, use the method. + After calling this method, you can no longer use the object. To temporarily pause an object, use the method. This method shut downs the object without processing queued requests. Any pending requests are unable to complete. @@ -542,9 +542,9 @@ The following code example demonstrates calling the `Close` method: `"HTTP/"` plus the hostname. - The property can be used by an application to review the list of default SPNs which will be used for authentication if no custom list is supplied. If other SPNs are needed, an application can add them using one of the methods. + The property can be used by an application to review the list of default SPNs which will be used for authentication if no custom list is supplied. If other SPNs are needed, an application can add them using one of the methods. - It is not safe when using extended protection to make policy decisions based on the requested URL, since this can be spoofed. Rather, applications should rely on the or properties to make such policy decisions. + It is not safe when using extended protection to make policy decisions based on the requested URL, since this can be spoofed. Rather, applications should rely on the or properties to make such policy decisions. ]]> @@ -602,16 +602,16 @@ The following code example demonstrates calling the `Close` method: method is called, usually within an application-defined callback method invoked by a delegate, to obtain the object that contains an incoming client request and its associated response. This method completes an operation previously started by calling the method. If the operation has not completed, this method blocks until it does. + The method is called, usually within an application-defined callback method invoked by a delegate, to obtain the object that contains an incoming client request and its associated response. This method completes an operation previously started by calling the method. If the operation has not completed, this method blocks until it does. - Because calling the method requires the object, this object is typically passed into a callback method by using the state object passed into the method. You can obtain this state object by using the property of the `asyncResult` object. + Because calling the method requires the object, this object is typically passed into a callback method by using the state object passed into the method. You can obtain this state object by using the property of the `asyncResult` object. For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). ## Examples - The following code example shows the implementation of a callback method that calls the method. + The following code example shows the implementation of a callback method that calls the method. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet13"::: @@ -820,9 +820,9 @@ The following code example demonstrates calling the `Close` method: method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. + Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. - This method blocks while waiting for an incoming request. If you want incoming requests to be processed asynchronously (on separate threads) so that your application does not block, use the method. + This method blocks while waiting for an incoming request. If you want incoming requests to be processed asynchronously (on separate threads) so that your application does not block, use the method. @@ -888,9 +888,9 @@ The following code example demonstrates calling the `Close` method: object will complete when the incoming request has been received. + This operation will not block. The returned object will complete when the incoming request has been received. - Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. + Before calling this method, you must call the method and add at least one URI prefix to listen for by adding the URI strings to the returned by the property. For a detailed description of prefixes, see the class overview. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1006,7 +1006,7 @@ The following code example demonstrates calling the `Close` method: , call the method. + To start an , call the method. @@ -1241,9 +1241,9 @@ The following code example demonstrates calling the `Close` method: or method. + This method must be called before you call the or method. - After you have started an object, you can use the method to stop it. + After you have started an object, you can use the method to stop it. > [!NOTE] > If this listener instance uses https, you must install and select a Server Certificate. Otherwise, an query of this will fail with an unexpected close of the connection. You can configure Server Certificates and other listener options by using [HttpCfg.exe](/windows/win32/http/httpcfg-exe). @@ -1251,7 +1251,7 @@ The following code example demonstrates calling the `Close` method: ## Examples - The following code example demonstrates using the method to begin processing incoming requests. + The following code example demonstrates using the method to begin processing incoming requests. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet12"::: @@ -1309,13 +1309,13 @@ The following code example demonstrates calling the `Close` method: ## Remarks If this instance is already stopped, calling this method has no effect. - After you have stopped an object, you can use the method to restart it. + After you have stopped an object, you can use the method to restart it. This method does not block to finish sending responses for currently accepted connections. ## Examples -The following code example demonstrates using the method to stop processing incoming requests. +The following code example demonstrates using the method to stop processing incoming requests. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet2"::: @@ -1379,7 +1379,7 @@ The following code example demonstrates using the method instead of calling this method. + Applications should use the method instead of calling this method. ]]> diff --git a/xml/System.Net/HttpListenerContext.xml b/xml/System.Net/HttpListenerContext.xml index ead27f62f80..1c251b816df 100644 --- a/xml/System.Net/HttpListenerContext.xml +++ b/xml/System.Net/HttpListenerContext.xml @@ -56,7 +56,7 @@ ## Remarks This class provides the information related to a client's Hypertext Transfer Protocol (HTTP) request being processed by an object. This class also has methods that allow an object to accept a WebSocket connection. - The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. + The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. Closing an object sends the response to the client and frees any resources used by the . Aborting an object discards the response to the client if it has not already been sent, and frees any resources used by the . After closing or aborting an object, you cannot reference its methods or properties. If you do so, you will receive an exception. @@ -138,7 +138,7 @@ object will complete after the WebSocket connection has been accepted. + This operation will not block. The returned object will complete after the WebSocket connection has been accepted. The size of the receive buffer is 16,385 bytes. The WebSocket keep-alive interval is set to the default value of 30,000 (30 seconds). @@ -209,7 +209,7 @@ object will complete after the WebSocket connection has been accepted. + This operation will not block. The returned object will complete after the WebSocket connection has been accepted. The size of the receive buffer is 16,385 bytes. @@ -284,7 +284,7 @@ > object will complete after the WebSocket connection has been accepted. + This operation will not block. The returned > object will complete after the WebSocket connection has been accepted. ]]> @@ -379,7 +379,7 @@ object will complete after the WebSocket connection has been accepted. + This operation will not block. The returned object will complete after the WebSocket connection has been accepted. ]]> diff --git a/xml/System.Net/HttpListenerException.xml b/xml/System.Net/HttpListenerException.xml index 0f7c33ed5e4..c034df7e98f 100644 --- a/xml/System.Net/HttpListenerException.xml +++ b/xml/System.Net/HttpListenerException.xml @@ -128,7 +128,7 @@ and properties using the most recent Windows error. + This constructor sets the and properties using the most recent Windows error. ]]> diff --git a/xml/System.Net/HttpListenerPrefixCollection.xml b/xml/System.Net/HttpListenerPrefixCollection.xml index b3fbea003df..b988d71ca49 100644 --- a/xml/System.Net/HttpListenerPrefixCollection.xml +++ b/xml/System.Net/HttpListenerPrefixCollection.xml @@ -548,11 +548,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. @@ -776,11 +776,11 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - For a detailed description of enumerators, see the documentation for the class and the method. + For a detailed description of enumerators, see the documentation for the class and the method. ]]> diff --git a/xml/System.Net/HttpListenerRequest.xml b/xml/System.Net/HttpListenerRequest.xml index d0297082406..131805bc2ed 100644 --- a/xml/System.Net/HttpListenerRequest.xml +++ b/xml/System.Net/HttpListenerRequest.xml @@ -56,7 +56,7 @@ ## Remarks When a client makes a request to a Uniform Resource Identifier (URI) handled by an object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. - The object contains information about the request, such as the request string, string, and request body data (see the property). + The object contains information about the request, such as the request string, string, and request body data (see the property). To reply to the request, you must get the associated response using the property. @@ -303,7 +303,7 @@ object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . + An object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . @@ -438,7 +438,7 @@ For a complete list of request headers, see the enumeration and RFC 2616, available at [https://www.rfc-editor.org](https://www.rfc-editor.org/). - The is null when there is no `Content-Type` header in the request. + The is null when there is no `Content-Type` header in the request. @@ -672,7 +672,7 @@ object will complete when the certificate has been retrieved. + This operation will not block. The returned object will complete when the certificate has been retrieved. If a call to this method to retrieve the client's X.509 v.3 certificate is in progress, then another call to this method cannot be made. @@ -908,7 +908,7 @@ If the client transmits data (for example, using the HTTP `POST` method), the stream returned by this method contains that data. > [!NOTE] -> Closing the request does not close the stream returned by this property. When you no longer need the stream, you should close it by calling the method. +> Closing the request does not close the stream returned by this property. When you no longer need the stream, you should close it by calling the method. @@ -971,7 +971,7 @@ or property. + Your application requests client authentication using the or property. Your application does not receive an for requests from clients that are not successfully authenticated. @@ -1390,7 +1390,7 @@ property value from the object returned by . + In a URL, the query information is separated from the path information by a question mark (?). Name/value pairs are separated by an equals sign (=). To access the query data as a single string, get the property value from the object returned by . > [!NOTE] > Queries without an equals sign (for example, `http://www.contoso.com/query.htm?Name`) are added to the `null` key in the . @@ -1694,7 +1694,7 @@ An application could use the property to perform custom authentication using calls to the native Win32 [AcceptSecurityContext](/windows/win32/api/sspi/nf-sspi-acceptsecuritycontext) function. - If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. + If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. ]]> @@ -1899,7 +1899,7 @@ For a complete list of request headers, see the enumeration. - The is null when there is no `Referrer` header in the request or when the `Referrer` header is present in the request but does not parse to a valid . + The is null when there is no `Referrer` header in the request or when the `Referrer` header is present in the request but does not parse to a valid . @@ -1973,7 +1973,7 @@ For a complete list of request headers, see the enumeration. - The is null when there is no `User-Agent` header in the request. + The is null when there is no `User-Agent` header in the request. diff --git a/xml/System.Net/HttpListenerResponse.xml b/xml/System.Net/HttpListenerResponse.xml index 28cd34dca5d..415e8e118fa 100644 --- a/xml/System.Net/HttpListenerResponse.xml +++ b/xml/System.Net/HttpListenerResponse.xml @@ -60,7 +60,7 @@ ## Remarks When a client makes a request for a resource handled by an object, the request and response are made available to your application in an object. The request is represented by an object and is available in the property. The response is represented by an object and is available in the property. - You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. + You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. ]]> @@ -174,9 +174,9 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. - If the header specified in `name` does not exist, this method inserts a new header into the property's collection. If `name` is present in the collection, this method replaces the existing value with `value`. To add a value to an existing header without replacing the existing value, use the method. + If the header specified in `name` does not exist, this method inserts a new header into the property's collection. If `name` is present in the collection, this method replaces the existing value with `value`. To add a value to an existing header without replacing the existing value, use the method. @@ -247,7 +247,7 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. If the specified cookie does not exist in the property's collection, `cookie` is added. If the cookie exists in the collection, `cookie` replaces it. @@ -315,9 +315,9 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. - If the header specified in `header` does not exist, this method inserts a new header into the property's collection. If `header` is present in the collection, this method adds `value` to the existing values. To replace the value of an existing header, use the method. + If the header specified in `header` does not exist, this method inserts a new header into the property's collection. If `header` is present in the collection, this method adds `value` to the existing values. To replace the value of an existing header, use the method. ]]> @@ -466,7 +466,7 @@ array instead of writing the body data to the property and calling the method. + If you are sending body data with the response, you can use this method to send it as a array instead of writing the body data to the property and calling the method. This method closes the response stream and the associated with the response. @@ -808,21 +808,21 @@ instance as a template. Customize the template response once and, instead of configuring each response separately, call the method to configure a new response based on property values in the template response. + If you regularly change many properties from their default values to a fixed set of new values, it is convenient to use an instance as a template. Customize the template response once and, instead of configuring each response separately, call the method to configure a new response based on property values in the template response. The following properties are copied from `templateResponse` to the current instance. -- +- -- +- -- +- -- +- -- +- -- +- @@ -892,7 +892,7 @@ For a complete list of response headers, see the enumeration. > [!NOTE] -> If you attempt to set a Content-Length, Keep-Alive, Transfer-Encoding, or WWW-Authenticate header using the Headers property, an exception will be thrown. Use the or properties to set these headers. You cannot set the Transfer-Encoding or WWW-Authenticate headers manually. +> If you attempt to set a Content-Length, Keep-Alive, Transfer-Encoding, or WWW-Authenticate header using the Headers property, an exception will be thrown. Use the or properties to set these headers. You cannot set the Transfer-Encoding or WWW-Authenticate headers manually. @@ -1156,7 +1156,7 @@ method is used to redirect a client to the new location for a resource. This method sets the response's `Location` header to `url`, the property to , and the property to "Found". + The method is used to redirect a client to the new location for a resource. This method sets the response's `Location` header to `url`, the property to , and the property to "Found". @@ -1338,7 +1338,7 @@ , , and properties are the same. If these three pieces of information are the same, the method attempts to update the cookie. The name and domain comparisons are not case sensitive, but the path comparison is case sensitive. + Two cookies are considered the same if the values of their , , and properties are the same. If these three pieces of information are the same, the method attempts to update the cookie. The name and domain comparisons are not case sensitive, but the path comparison is case sensitive. @@ -1463,7 +1463,7 @@ value. + The status description typically provides details that explain the value. @@ -1527,7 +1527,7 @@ method to send the response and release resources held by an . To discard the response and release the resources held by this instance, use the method. + Use the method to send the response and release resources held by an . To discard the response and release the resources held by this instance, use the method. ]]> diff --git a/xml/System.Net/HttpListenerTimeoutManager.xml b/xml/System.Net/HttpListenerTimeoutManager.xml index 68c0761d3ef..6a036b12fb1 100644 --- a/xml/System.Net/HttpListenerTimeoutManager.xml +++ b/xml/System.Net/HttpListenerTimeoutManager.xml @@ -211,7 +211,7 @@ This timeout is only enforced after the first request on the connection is routed to the . - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. ]]> @@ -262,7 +262,7 @@ This timeout is only enforced after the first request on the connection is routed to the . - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. ]]> @@ -317,7 +317,7 @@ ## Remarks The default response send rate is 150 bytes-per-second. - To disable this timer, set to MAXULONG. + To disable this timer, set to MAXULONG. ]]> diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index bb996b3336e..ee1c9302df9 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -81,15 +81,15 @@ The class provides support for the properties and methods defined in and for additional properties and methods that enable the user to interact directly with servers using HTTP. - Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. + Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. - The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. + The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. - When you want to send data to the resource, the method returns a object to use to send data. The and methods provide asynchronous access to the send data stream. + When you want to send data to the resource, the method returns a object to use to send data. The and methods provide asynchronous access to the send data stream. For client authentication with , the client certificate must be installed in the My certificate store of the current user. - The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. + The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. exposes common HTTP header values sent to the Internet resource as properties, set by methods, or set by the system; the following table contains a complete list. You can set other headers in the property as name/value pairs. Note that servers and caches may change or add headers during the request. @@ -105,18 +105,18 @@ |`Date`|Set by the system to current date.| |`Host`|Set by the system to current host information.| |`If-Modified-Since`|Set by the property.| -|`Range`|Set by the method.| +|`Range`|Set by the method.| |`Referer`|Set by the property.| |`Transfer-Encoding`|Set by the property (the property must be `true`).| |`User-Agent`|Set by the property.| > [!NOTE] -> is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. +> is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. > [!NOTE] -> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. +> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. > [!NOTE] > For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. @@ -149,7 +149,7 @@ For apps that use TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPCl [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] -Both constructors are obsolete and should not be used. Call the method to initialize new objects. +Both constructors are obsolete and should not be used. Call the method to initialize new objects. ]]> @@ -331,9 +331,9 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . + The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . - The method will synchronously execute the callback specified to the or methods if the method is called while either of these operations are outstanding. This can lead to potential deadlock issues. + The method will synchronously execute the callback specified to the or methods if the method is called while either of these operations are outstanding. This can lead to potential deadlock issues. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing](/dotnet/framework/network-programming/network-tracing). @@ -499,7 +499,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a byte range header to the request. + The method adds a byte range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -595,7 +595,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a byte range header to the request. + The method adds a byte range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -683,7 +683,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a byte range header to the request. + The method adds a byte range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -781,7 +781,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a byte range header to the request. + The method adds a byte range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -869,7 +869,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a Range header to the request. + The method adds a Range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -959,7 +959,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a Range header to the request. + The method adds a Range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -1053,7 +1053,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a Range header to the request. + The method adds a Range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -1149,7 +1149,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method adds a Range header to the request. + The method adds a Range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -1319,11 +1319,11 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set to `true` if you want the request to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the request to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. - If is set to `false`, all responses with an HTTP status code from 300 to 399 is returned to the application. + If is set to `false`, all responses with an HTTP status code from 300 to 399 is returned to the application. - The Authorization header is cleared on auto-redirects and automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. The and related class are used to implement a custom authentication module. The method registers a custom authentication module. + The Authorization header is cleared on auto-redirects and automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. The and related class are used to implement a custom authentication module. The method registers a custom authentication module. @@ -1435,7 +1435,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - When is `true`, the data is buffered in memory so it is ready to be resent in the event of redirections or authentication requests. + When is `true`, the data is buffered in memory so it is ready to be resent in the event of redirections or authentication requests. ## Examples The following code example uses the property to disable data buffering. @@ -1558,14 +1558,14 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method starts an asynchronous request for a stream used to send data for the . The asynchronous callback method uses the method to return the actual stream. + The method starts an asynchronous request for a stream used to send data for the . The asynchronous callback method uses the method to return the actual stream. - The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. + The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. To learn more about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). > [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. +> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1573,7 +1573,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example uses the method to make an asynchronous request for a stream instance. + The following code example uses the method to make an asynchronous request for a stream instance. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.vb" id="Snippet2"::: @@ -1658,18 +1658,18 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method starts an asynchronous request for a response from the Internet resource. The asynchronous callback method uses the method to return the actual . + The method starts an asynchronous request for a response from the Internet resource. The asynchronous callback method uses the method to return the actual . - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` + A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` - If a is thrown, use the and properties of the exception to determine the response from the server. + If a is thrown, use the and properties of the exception to determine the response from the server. - The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. + The method requires some synchronous setup tasks to complete (DNS resolution, proxy detection, and TCP socket connection, for example) before this method becomes asynchronous. As a result, this method should never be called on a user interface (UI) thread because it might take considerable time (up to several minutes depending on network settings) to complete the initial synchronous setup tasks before an exception for an error is thrown or the method succeeds. To learn more about the thread pool, see [The managed thread pool](/dotnet/standard/threading/the-managed-thread-pool). > [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. +> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1677,7 +1677,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example uses the method to make an asynchronous request for an Internet resource. + The following code example uses the method to make an asynchronous request for an Internet resource. > [!NOTE] > In the case of asynchronous requests, it is the responsibility of the client application to implement its own time-out mechanism. The following code example shows how to do it. @@ -1776,7 +1776,7 @@ Both constructors are obsolete and should not b An application can add a certificate to a collection, but might not have access rights to it. To use a certificate contained in the collection, the application must have the same access rights as the entity that issued the certificate. > [!NOTE] -> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. +> The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. > [!NOTE] > For performance reasons, you shouldn't add a client certificate to a unless you know the server will ask for it. @@ -1842,7 +1842,7 @@ Both constructors are obsolete and should not b To clear the `Connection` HTTP header, set the property to `null`. - Changing the property after the request has been started by calling the , , , or method throws an . + Changing the property after the request has been started by calling the , , , or method throws an . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -1991,7 +1991,7 @@ Both constructors are obsolete and should not b Any value other than -1 in the property indicates that the request uploads data and that only methods that upload data are allowed to be set in the property. - After the property is set to a value, that number of bytes must be written to the request stream that is returned by calling the method or both the and the methods. + After the property is set to a value, that number of bytes must be written to the request stream that is returned by calling the method or both the and the methods. > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -2275,7 +2275,7 @@ Both constructors are obsolete and should not b The property provides an instance of the class that contains the cookies associated with this request. - is `null` by default. You must assign a object to the property to have cookies returned in the property of the returned by the method. + is `null` by default. You must assign a object to the property to have cookies returned in the property of the returned by the method. > [!NOTE] > For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. @@ -2449,7 +2449,7 @@ Both constructors are obsolete and should not b > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - If the is set and an attempt is made to send a with no body, then a will be thrown by the , , and methods. + If the is set and an attempt is made to send a with no body, then a will be thrown by the , , and methods. ]]> @@ -2690,17 +2690,17 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. + The method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. > [!NOTE] > - You must set the value of the property before writing data to the stream. -> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. +> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example uses the method to end an asynchronous request for a stream instance. + The following code example uses the method to end an asynchronous request for a stream instance. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/BeginGetRequestStream/httpwebrequest_begingetrequeststream.vb" id="Snippet2"::: @@ -2783,13 +2783,13 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method completes an asynchronous request for a stream that was started by the method and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. + The method completes an asynchronous request for a stream that was started by the method and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. - Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. + Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. > [!NOTE] > - If you need to set the value of the property before writing data to the stream. -> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. +> - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ]]> @@ -2867,10 +2867,10 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method completes an asynchronous request for an Internet resource that was started by calling the method. + The method completes an asynchronous request for an Internet resource that was started by calling the method. > [!CAUTION] -> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. +> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -2878,7 +2878,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example uses the method to end an asynchronous request for an Internet resource. + The following code example uses the method to end an asynchronous request for an Internet resource. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: @@ -3123,14 +3123,14 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. + The method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. If an application needs to set the value of the property, then this must be done before retrieving the stream. - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. + You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. +> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3138,7 +3138,7 @@ The GetHashCode method returns a hash code of the web request. This value can be ## Examples - The following code example uses the method to return a stream instance. + The following code example uses the method to return a stream instance. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: @@ -3230,16 +3230,16 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a stream to use to send data for the and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. + The method returns a stream to use to send data for the and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. - Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. + Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. If an application needs to set the value of the property, then this must be done before retrieving the stream. - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. + You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. +> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3325,23 +3325,23 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a object that contains the response from the Internet resource. The actual instance returned is an , and can be typecast to that class to access HTTP-specific properties. + The method returns a object that contains the response from the Internet resource. The actual instance returned is an , and can be typecast to that class to access HTTP-specific properties. - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` + A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` > [!CAUTION] -> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. +> You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. When using the POST method, you must get the request stream, write the data to be posted, and close the stream. This method blocks waiting for content to post; if there is no time-out set and you do not provide content, the calling thread blocks indefinitely. > [!NOTE] -> Multiple calls to return the same response object; the request is not reissued. +> Multiple calls to return the same response object; the request is not reissued. > [!NOTE] -> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. +> Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. > [!NOTE] -> If a is thrown, use the and properties of the exception to determine the response from the server. +> If a is thrown, use the and properties of the exception to determine the response from the server. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3513,7 +3513,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The collection contains the protocol headers associated with the request. The following table lists the HTTP headers that are not stored in the collection but are either set by the system or set by properties or methods. + The collection contains the protocol headers associated with the request. The following table lists the HTTP headers that are not stored in the collection but are either set by the system or set by properties or methods. |Header|Set by| |------------|------------| @@ -3525,14 +3525,14 @@ The GetHashCode method returns a hash code of the web request. This value can be |Date|Set by the property.| |Host|Set by the property.| |If-Modified-Since|Set by the property.| -|Range|Set by the method.| +|Range|Set by the method.| |Referer|Set by the property.| |Transfer-Encoding|Set by the property (the property must be true).| |User-Agent|Set by the property.| - The method throws an if you try to set one of these protected headers. + The method throws an if you try to set one of these protected headers. - Changing the property after the request has been started by calling , , , or method throws an . + Changing the property after the request has been started by calling , , , or method throws an . You should not assume that the header values will remain unchanged, because Web servers and caches may change or add headers to a Web request. @@ -3691,7 +3691,7 @@ The GetHashCode method returns a hash code of the web request. This value can be > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - If the property is set and 304 (Not Modified) status code is returned, then a will be thrown by the , , and methods. + If the property is set and 304 (Not Modified) status code is returned, then a will be thrown by the , , and methods. @@ -3765,10 +3765,10 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set this property to `true` to send a `Connection` HTTP header with the value Keep-alive. An application uses to indicate a preference for persistent connections. When the property is `true`, the application makes persistent connections to the servers that support them. + Set this property to `true` to send a `Connection` HTTP header with the value Keep-alive. An application uses to indicate a preference for persistent connections. When the property is `true`, the application makes persistent connections to the servers that support them. > [!NOTE] -> When using HTTP/1.1, Keep-Alive is on by default. Setting to `false` may result in sending a `Connection: Close` header to the server. +> When using HTTP/1.1, Keep-Alive is on by default. Setting to `false` may result in sending a `Connection: Close` header to the server. @@ -3911,7 +3911,7 @@ The GetHashCode method returns a hash code of the web request. This value can be If the property is not explicitly set, it defaults to the value of the property. - If the length of the response header received exceeds the value of the property, the or methods will throw a with the property set to . + If the length of the response header received exceeds the value of the property, the or methods will throw a with the property set to . @@ -3987,7 +3987,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The value of the property affects the property. When you set the in the request, the corresponding media type is chosen from the list of character sets returned in the response `Content-type` HTTP header. + The value of the property affects the property. When you set the in the request, the corresponding media type is chosen from the list of character sets returned in the response `Content-type` HTTP header. ]]> @@ -4130,7 +4130,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. + An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. Pipelined connections are made only when the property is also `true`. @@ -4206,7 +4206,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - After a client request to a specific is successfully authenticated, if is `true` and credentials are supplied, the Authorization header is sent with each request to any that matches the specific up to the last forward slash. So if the client request successfully authenticated to a specific that contains the following: + After a client request to a specific is successfully authenticated, if is `true` and credentials are supplied, the Authorization header is sent with each request to any that matches the specific up to the last forward slash. So if the client request successfully authenticated to a specific that contains the following: `http://www.contoso.com/firstpath/` @@ -4236,7 +4236,7 @@ The GetHashCode method returns a hash code of the web request. This value can be The following dialog between client and server illustrates the effect of this property. The dialog assumes that basic authentication is in use. - is `false`: + is `false`: Client: GET someUrl @@ -4254,7 +4254,7 @@ The GetHashCode method returns a hash code of the web request. This value can be Server: 200 OK - is `true`: + is `true`: Client: GET someUrl @@ -4327,7 +4327,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The class supports only versions 1.0 and 1.1 of HTTP. Setting to a different version throws an exception. + The class supports only versions 1.0 and 1.1 of HTTP. Setting to a different version throws an exception. > [!NOTE] > To set the HTTP version of the current request, use the and fields of the class. @@ -4395,7 +4395,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. + The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. @@ -4405,14 +4405,14 @@ The GetHashCode method returns a hash code of the web request. This value can be - The destination contains a loopback address ( or ) or the destination contains an assigned to the local computer. -- The domain suffix of the destination matches the local computer's domain suffix (). +- The domain suffix of the destination matches the local computer's domain suffix (). - Changing the property after the request has been started by calling the , , , or method throws an . For information on the proxy element see [\<defaultProxy\> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings). + Changing the property after the request has been started by calling the , , , or method throws an . For information on the proxy element see [\<defaultProxy\> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings). ## Examples - The following code example uses the method to get the proxy information for the request. + The following code example uses the method to get the proxy information for the request. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Proxy/httpwebrequest_proxy.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Proxy/httpwebrequest_proxy.vb" id="Snippet1"::: @@ -4484,9 +4484,9 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property is used when writing to the stream returned by the method or reading from the stream returned by the method. + The property is used when writing to the stream returned by the method or reading from the stream returned by the method. - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. + Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. To specify the amount of time to wait for the request to complete, use the property. @@ -4637,7 +4637,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The object passed to by the call to . + The object passed to by the call to . Following a redirection header does not change the property. To get the actual URI that responded to the request, examine the property. @@ -4703,9 +4703,9 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - When is `true`, the request sends data to the Internet resource in segments. The Internet resource must support receiving chunked data. + When is `true`, the request sends data to the Internet resource in segments. The Internet resource must support receiving chunked data. - Changing the property after the request has been started by calling the , , , or method throws an . + Changing the property after the request has been started by calling the , , , or method throws an . @@ -4833,7 +4833,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property may be different from if the request is redirected. + The property may be different from if the request is redirected. @@ -5021,18 +5021,18 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . + is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . - The property must be set before the or method is called. Changing the property after calling the or method has no effect + The property must be set before the or method is called. Changing the property after calling the or method has no effect - The property has no effect on asynchronous requests made with the or method. + The property has no effect on asynchronous requests made with the or method. > [!CAUTION] -> In the case of asynchronous requests, the client application implements its own time-out mechanism. Refer to the example in the method. +> In the case of asynchronous requests, the client application implements its own time-out mechanism. Refer to the example in the method. To specify the amount of time to wait before a read or write operation times out, use the property. - A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. + A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. @@ -5098,7 +5098,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before you can set the property, you must first set the property to `true`. Clearing by setting it to `null` has no effect on the value of . + Before you can set the property, you must first set the property to `true`. Clearing by setting it to `null` has no effect on the value of . Values assigned to the property replace any existing contents. @@ -5181,7 +5181,7 @@ The GetHashCode method returns a hash code of the web request. This value can be If you control the back-end server, as an alternative you might consider turning off authentication persistence. This increases performance to a lesser degree, but it is safer. For more details, see [AuthPersistence](https://learn.microsoft.com/previous-versions/iis/6.0-sdk/ms525244(v=vs.90)). > [!NOTE] -> If both and are set to `true`, each request is sent using a connection from the unsafe pool, but with an Authorization header. +> If both and are set to `true`, each request is sent using a connection from the unsafe pool, but with an Authorization header. ]]> diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index 188cd4281de..80d55169c56 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -89,7 +89,7 @@ > [!NOTE] > Do not confuse with the class that is used in ASP.NET applications and whose methods and properties are exposed through ASP.NET's intrinsic `Response` object. - You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. + You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. @@ -97,13 +97,13 @@ |Header|Property| |------------|--------------| -|Content-Encoding|| -|Content-Length|| -|Content-Type|| -|Last-Modified|| -|Server|| +|Content-Encoding|| +|Content-Length|| +|Content-Type|| +|Last-Modified|| +|Server|| -The contents of the response from the Internet resource are returned as a by calling the method. +The contents of the response from the Internet resource are returned as a by calling the method. @@ -374,11 +374,11 @@ The contents of the response from the Internet resource are returned as a method closes the response stream and releases the connection to the resource for reuse by other requests. + The method closes the response stream and releases the connection to the resource for reuse by other requests. You should not access any properties of the object after the call to the `Close` method. On .NET Core, an is thrown. - You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. + You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -504,7 +504,7 @@ The contents of the response from the Internet resource are returned as a property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. + The property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. @@ -883,12 +883,12 @@ The GetHashCode method returns a hash code of the web response instance. This va to retrieve the contents of particular headers. You must specify which header you want to return. + Use to retrieve the contents of particular headers. You must specify which header you want to return. ## Examples - This example creates a Web request and queries for a response. If the site requires authentication, this example will respond with a challenge string. This string is extracted using . + This example creates a Web request and queries for a response. If the site requires authentication, this example will respond with a challenge string. This string is extracted using . :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/GetResponseHeader/httpwebresponse_getresponseheader.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/GetResponseHeader/httpwebresponse_getresponseheader.vb" id="Snippet1"::: @@ -946,10 +946,10 @@ The GetHashCode method returns a hash code of the web response instance. This va method returns the data stream from the requested Internet resource. + The method returns the data stream from the requested Internet resource. > [!NOTE] -> You must call one of the , , , or methods to close the stream and release the connection for reuse. It's not necessary to close or dispose both and instances, but doing so doesn't cause an error. Failure to close or dispose the stream will cause your application to run out of connections. +> You must call one of the , , , or methods to close the stream and release the connection for reuse. It's not necessary to close or dispose both and instances, but doing so doesn't cause an error. Failure to close or dispose the stream will cause your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -957,7 +957,7 @@ The GetHashCode method returns a hash code of the web response instance. This va ## Examples - The following example demonstrates how to use to return the instance used to read the response from the server. + The following example demonstrates how to use to return the instance used to read the response from the server. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/GetResponseStream/httpwebresponse_getresponsestream.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/GetResponseStream/httpwebresponse_getresponsestream.vb" id="Snippet1"::: @@ -1019,11 +1019,11 @@ The GetHashCode method returns a hash code of the web response instance. This va |Header|Property| |------------|--------------| -|Content-Encoding|| -|Content-Length|| -|Content-Type|| -|Last-Modified|| -|Server|| +|Content-Encoding|| +|Content-Length|| +|Content-Type|| +|Last-Modified|| +|Server|| @@ -1202,12 +1202,12 @@ The GetHashCode method returns a hash code of the web response instance. This va returns the method that is used to return the response. Common HTTP methods are GET, HEAD, POST, PUT, and DELETE. + returns the method that is used to return the response. Common HTTP methods are GET, HEAD, POST, PUT, and DELETE. ## Examples - The following example checks the string contained in , to determine the Http method invoked by the Web server. + The following example checks the string contained in , to determine the Http method invoked by the Web server. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.vb" id="Snippet1"::: @@ -1329,7 +1329,7 @@ The GetHashCode method returns a hash code of the web response instance. This va The property will use the Content-Location header if present. - Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. + Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. @@ -1455,12 +1455,12 @@ The GetHashCode method returns a hash code of the web response instance. This va parameter is a number that indicates the status of the HTTP response. The expected values for status are defined in the class. + The parameter is a number that indicates the status of the HTTP response. The expected values for status are defined in the class. ## Examples - The following example uses to verify that the status of the is OK. + The following example uses to verify that the status of the is OK. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.vb" id="Snippet1"::: @@ -1525,7 +1525,7 @@ The GetHashCode method returns a hash code of the web response instance. This va ## Examples - The following example uses to verify that the status of the is OK. + The following example uses to verify that the status of the is OK. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.vb" id="Snippet2"::: diff --git a/xml/System.Net/IAuthenticationModule.xml b/xml/System.Net/IAuthenticationModule.xml index ea1d80f5ef6..183bcfe3b0a 100644 --- a/xml/System.Net/IAuthenticationModule.xml +++ b/xml/System.Net/IAuthenticationModule.xml @@ -51,7 +51,7 @@ Authentication modules conduct the entire authentication process with a server, responding to an authentication challenge as appropriate. This process may consist of requests to an authentication server separate from the resource server, as well as any other activities required to properly authenticate a request for a URI. - Custom authentication modules should implement the interface and then register with the method. Authentication modules are also registered at program initialization by reading the configuration file. + Custom authentication modules should implement the interface and then register with the method. Authentication modules are also registered at program initialization by reading the configuration file. @@ -124,12 +124,12 @@ method conducts the authentication process with the server and returns an instance to the . + The method conducts the authentication process with the server and returns an instance to the . ## Examples - The following example shows how to use the method. For a complete example refer to the class. + The following example shows how to use the method. For a complete example refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet3"::: @@ -184,7 +184,7 @@ property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. + The property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. @@ -242,7 +242,7 @@ property is set to `true` to indicate that the authentication module can respond with a valid instance when the method is called. + The property is set to `true` to indicate that the authentication module can respond with a valid instance when the method is called. @@ -315,12 +315,12 @@ property is `true`, the method will return an instance of the class containing an authentication message. + When the property is `true`, the method will return an instance of the class containing an authentication message. ## Examples - The following example shows how to use the method. For a complete example refer to the class. + The following example shows how to use the method. For a complete example refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet4"::: diff --git a/xml/System.Net/ICertificatePolicy.xml b/xml/System.Net/ICertificatePolicy.xml index 86d7cd1df3c..e519222b842 100644 --- a/xml/System.Net/ICertificatePolicy.xml +++ b/xml/System.Net/ICertificatePolicy.xml @@ -16,22 +16,22 @@ Validates a server certificate. - interface is used to provide custom security certificate validation for an application. The default policy is to allow valid certificates, as well as valid certificates that have expired. To change this policy, implement the interface with a different policy, and then assign that policy to . - - uses the Security Support Provider Interface (SSPI). For more information, see the SSPI documentation on MSDN. - - - -## Examples - The following example creates a certificate policy that returns `false` for any certificate problem and prints a message that indicates the problem on the console. The CertificateProblem enum defines SSPI constants for certificate problems, and the private GetProblemMessage method creates a printable message about the problem. - + interface is used to provide custom security certificate validation for an application. The default policy is to allow valid certificates, as well as valid certificates that have expired. To change this policy, implement the interface with a different policy, and then assign that policy to . + + uses the Security Support Provider Interface (SSPI). For more information, see the SSPI documentation on MSDN. + + + +## Examples + The following example creates a certificate policy that returns `false` for any certificate problem and prints a message that indicates the problem on the console. The CertificateProblem enum defines SSPI constants for certificate problems, and the private GetProblemMessage method creates a printable message about the problem. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic ICertificatePolicy Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ICertificatePolicy/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/ICertificatePolicy/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Net/ICertificatePolicy/Overview/source.vb" id="Snippet1"::: + ]]> @@ -68,13 +68,13 @@ if the certificate should be honored; otherwise, . - method implements the application certificate validation policy. The method can examine the `srvPoint`, `certificate`, `request`, and `certificateProblem` parameters to determine whether the certificate should be honored. - - The `certificateProblem` parameter is a Security Support Provider Interface (SSPI) status code. For more information, see the SSPI documentation on MSDN. - + method implements the application certificate validation policy. The method can examine the `srvPoint`, `certificate`, `request`, and `certificateProblem` parameters to determine whether the certificate should be honored. + + The `certificateProblem` parameter is a Security Support Provider Interface (SSPI) status code. For more information, see the SSPI documentation on MSDN. + ]]> diff --git a/xml/System.Net/ICredentialPolicy.xml b/xml/System.Net/ICredentialPolicy.xml index e3e27714cc5..a1fc5c6b1f8 100644 --- a/xml/System.Net/ICredentialPolicy.xml +++ b/xml/System.Net/ICredentialPolicy.xml @@ -51,7 +51,7 @@ > [!NOTE] > policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. - Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. + Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. An policy affects all instances of with non-null credentials in the current application domain. The policy cannot be overridden on individual requests. @@ -119,9 +119,9 @@ policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. + After an policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. - When the original request has been redirected or proxy authentication is required, the resource identified by `challengeUri` can be different from the requested resource that is specified in . In the case of redirection, `challengeUri` contains the actual destination . If proxy authentication is required, `challengeUri` contains the address of the proxy server that requires client authentication. + When the original request has been redirected or proxy authentication is required, the resource identified by `challengeUri` can be different from the requested resource that is specified in . In the case of redirection, `challengeUri` contains the actual destination . If proxy authentication is required, `challengeUri` contains the address of the proxy server that requires client authentication. ]]> diff --git a/xml/System.Net/ICredentials.xml b/xml/System.Net/ICredentials.xml index 1b4cfa0af70..02aa7edc0b6 100644 --- a/xml/System.Net/ICredentials.xml +++ b/xml/System.Net/ICredentials.xml @@ -56,13 +56,13 @@ interface provides the method to objects that supply network credentials to applications. + The interface provides the method to objects that supply network credentials to applications. ## Examples The following example illustrates how to use the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Net/ICredentials/Overview/icredential.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/ICredentials/Overview/icredential.vb" id="Snippet1"::: @@ -126,12 +126,12 @@ method returns a instance that contains the credentials that are associated with the specified URI and authorization scheme. When no credentials are available, the method returns `null`. + The method returns a instance that contains the credentials that are associated with the specified URI and authorization scheme. When no credentials are available, the method returns `null`. ## Examples - The following uses to retrieve a instance. + The following uses to retrieve a instance. :::code language="csharp" source="~/snippets/csharp/System.Net/ICredentials/Overview/icredential.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/ICredentials/Overview/icredential.vb" id="Snippet1"::: diff --git a/xml/System.Net/IPAddress.xml b/xml/System.Net/IPAddress.xml index d27b40c390a..c30d30d4d36 100644 --- a/xml/System.Net/IPAddress.xml +++ b/xml/System.Net/IPAddress.xml @@ -170,7 +170,7 @@ ## Remarks The is created with the property set to `address`. - If the length of `address` is 4, constructs an IPv4 address; otherwise, an IPv6 address with a scope of 0 is constructed. + If the length of `address` is 4, constructs an IPv4 address; otherwise, an IPv6 address with a scope of 0 is constructed. The array is assumed to be in network byte order with the most significant byte first in index position 0. @@ -482,9 +482,9 @@ . + This property is obsolete. Use . - To convert to dotted-quad notation, use the method. + To convert to dotted-quad notation, use the method. ]]> @@ -605,7 +605,7 @@ method uses the field to indicate that a instance must listen for client activity on all network interfaces. + The method uses the field to indicate that a instance must listen for client activity on all network interfaces. The field is equivalent to 0.0.0.0 in dotted-quad notation. @@ -745,7 +745,7 @@ method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same IP address. + The method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same IP address. ]]> @@ -856,7 +856,7 @@ method returns a hash code of the IP address. This value can be used as a key in hash tables. + The method returns a hash code of the IP address. This value can be used as a key in hash tables. ]]> @@ -925,7 +925,7 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. + The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. ]]> @@ -985,7 +985,7 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. + The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. ]]> @@ -1045,7 +1045,7 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. + The method converts multibyte integer values that are stored on the host system from the byte order used by the host to the byte order used by the network. ]]> @@ -1236,7 +1236,7 @@ method uses the field to indicate that a must not listen for client activity. The field is equivalent to 0:0:0:0:0:0:0:0 in colon-hexadecimal notation, or to ::0 in compact notation. + The method uses the field to indicate that a must not listen for client activity. The field is equivalent to 0:0:0:0:0:0:0:0 in colon-hexadecimal notation, or to ::0 in compact notation. @@ -1587,14 +1587,14 @@ method compares `address` to and returns `true` if the two IP addresses are the same. + The method compares `address` to and returns `true` if the two IP addresses are the same. - In the case of IPv4, that the method returns `true` for any IP address of the form 127.X.Y.Z (where X, Y, and Z are in the range 0-255), not just (127.0.0.1). + In the case of IPv4, that the method returns `true` for any IP address of the form 127.X.Y.Z (where X, Y, and Z are in the range 0-255), not just (127.0.0.1). ## Examples - The following code example uses the method to determine whether the specified address is a loopback address. + The following code example uses the method to determine whether the specified address is a loopback address. :::code language="csharp" source="~/snippets/csharp/System.Net/IPAddress/IsLoopback/isloopback.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPAddress/IsLoopback/isloopback.vb" id="Snippet1"::: @@ -1791,7 +1791,7 @@ ## Remarks Dual-stack sockets always require IPv6 addresses. The ability to interact with an IPv4 address requires the use of the IPv4-mapped IPv6 address format. Any IPv4 addresses must be represented in the IPv4-mapped IPv6 address format which enables an IPv6 only application to communicate with an IPv4 node. The IPv4-mapped IPv6 address format allows the IPv4 address of an IPv4 node to be represented as an IPv6 address. The IPv4 address is encoded into the low-order 32 bits of the IPv6 address, and the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. The IPv4-mapped IPv6 address format is specified in RFC 4291. For more information, see [www.ietf.org/rfc/rfc4291.txt](https://go.microsoft.com/fwlink/?LinkID=92231). - If you want to use to convert an IPv4 address from IPv6 format to IPv4 format, you must first ensure that you've got an IPv4 address. Call , which will return `true` if the IP address is originally IPv4 written as IPv6, or `false` otherwise. If returns `true`, use to make the conversion. + If you want to use to convert an IPv4 address from IPv6 format to IPv4 format, you must first ensure that you've got an IPv4 address. Call , which will return `true` if the IP address is originally IPv4 written as IPv6, or `false` otherwise. If returns `true`, use to make the conversion. ]]> @@ -1920,12 +1920,12 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. + The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. ## Examples - The following example uses the method to convert a short value from network byte order to host byte order. + The following example uses the method to convert a short value from network byte order to host byte order. :::code language="csharp" source="~/snippets/csharp/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.vb" id="Snippet1"::: @@ -1994,12 +1994,12 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. + The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. ## Examples - The following example uses the method to convert an integer value from network byte order to host byte order. + The following example uses the method to convert an integer value from network byte order to host byte order. :::code language="csharp" source="~/snippets/csharp/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.vb" id="Snippet2"::: @@ -2068,12 +2068,12 @@ ## Remarks Different computers use different conventions for ordering the bytes within multibyte integer values. Some computers put the most significant byte first (known as big-endian order) and others put the least-significant byte first (known as little-endian order). To work with computers that use different byte ordering, all integer values that are sent over the network are sent in network byte order which has the most significant byte first. - The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. + The method converts multibyte integer values that are stored on the host system from the byte order used by the network to the byte order used by the host. ## Examples - The following example uses the method to convert a long value from network byte order to host byte order. + The following example uses the method to convert a long value from network byte order to host byte order. :::code language="csharp" source="~/snippets/csharp/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPAddress/NetworkToHostOrder/ipaddress_networktohost.vb" id="Snippet3"::: @@ -2135,7 +2135,7 @@ method uses the field to indicate that a must not listen for client activity. The field is equivalent to 255.255.255.255 in dotted-quad notation. + The method uses the field to indicate that a must not listen for client activity. The field is equivalent to 255.255.255.255 in dotted-quad notation. @@ -2247,7 +2247,7 @@ method creates an instance from an IP address expressed in dotted-quad notation for IPv4 and in colon-hexadecimal notation for IPv6. + The static method creates an instance from an IP address expressed in dotted-quad notation for IPv4 and in colon-hexadecimal notation for IPv6. The number of parts (each part is separated by a period) in `ipString` determines how the IP address is constructed. A one part address is stored directly in the network address. A two part address, convenient for specifying a class A address, puts the leading part in the first byte and the trailing part in the right-most three bytes of the network address. A three part address, convenient for specifying a class B address, puts the first part in the first byte, the second part in the second byte, and the final part in the right-most two bytes of the network address. For example: @@ -2262,7 +2262,7 @@ |1 -- "0x2F"|0.0.0.47| ## Examples - The following code converts a string that contains an IP address, in dotted-quad notation for IPv4 or in colon-hexadecimal notation for IPv6, into an instance of the class. Then it uses the overloaded method to display the address in standard notation. + The following code converts a string that contains an IP address, in dotted-quad notation for IPv4 or in colon-hexadecimal notation for IPv6, into an instance of the class. Then it uses the overloaded method to display the address in standard notation. :::code language="csharp" source="~/snippets/csharp/System.Net/IPAddress/Parse/parse.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPAddress/Parse/parse.vb" id="Snippet1"::: @@ -2380,7 +2380,7 @@ changes depending on the context in which it is used. + The meaning of changes depending on the context in which it is used. - Link-local address. On a host with multiple interfaces connected to separate links, the same link-local address can be assigned to multiple interfaces. To eliminate this ambiguity, a scope identifier is used to specify the interface over which messages are exchanged. @@ -2876,7 +2876,7 @@ The scope identifier is > 0x00000000FFFFFFFF method converts the IP address that is stored in the property to either IPv4 dotted-quad or IPv6 colon-hexadecimal notation. + The method converts the IP address that is stored in the property to either IPv4 dotted-quad or IPv6 colon-hexadecimal notation. ]]> @@ -3086,7 +3086,7 @@ The scope identifier is > 0x00000000FFFFFFFF method creates an instance from an IP address expressed in dotted-quad notation for IPv4 and in colon-hexadecimal notation for IPv6. + The static method creates an instance from an IP address expressed in dotted-quad notation for IPv4 and in colon-hexadecimal notation for IPv6. The number of parts (each part is separated by a period) in `ipString` determines how the IP address is constructed. A one part address is stored directly in the network address. A two part address, convenient for specifying a class A address, puts the leading part in the first byte and the trailing part in the right-most three bytes of the network address. A three part address, convenient for specifying a class B address, puts the first part in the first byte, the second part in the second byte, and the final part in the right-most two bytes of the network address. For example: diff --git a/xml/System.Net/IPEndPoint.xml b/xml/System.Net/IPEndPoint.xml index 14f6ce33765..86bbafe4f0d 100644 --- a/xml/System.Net/IPEndPoint.xml +++ b/xml/System.Net/IPEndPoint.xml @@ -548,7 +548,7 @@ method returns a hash code of the IP endpoint instance. This value can be used as a key in hash tables. + The method returns a hash code of the IP endpoint instance. This value can be used as a key in hash tables. ]]> @@ -941,7 +941,7 @@ Literal IPv6 addresses require to be enclosed in square brackets [] when passing method to serialize endpoint information into a instance. + The following example uses the method to serialize endpoint information into a instance. :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/Overview/ipendpoint.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/Overview/ipendpoint.vb" id="Snippet4"::: diff --git a/xml/System.Net/IPEndPointCollection.xml b/xml/System.Net/IPEndPointCollection.xml index 404ba484929..14f83df637f 100644 --- a/xml/System.Net/IPEndPointCollection.xml +++ b/xml/System.Net/IPEndPointCollection.xml @@ -27,19 +27,19 @@ Represents a collection used to store network endpoints as objects. - class is derived from the class. - - The class contains the host and local or remote port information needed by an application to connect to a service on a host. By combining the host's IP address and port number of a service, the class forms a connection point to a service. - - The class is used by classes in the namespace. - + class is derived from the class. + + The class contains the host and local or remote port information needed by an application to connect to a service on a host. By combining the host's IP address and port number of a service, the class forms a connection point to a service. + + The class is used by classes in the namespace. + ]]> - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + A can support multiple readers concurrently, as long as the collection is not modified. Even so, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -92,21 +92,21 @@ The object to insert. The value can be for reference types. Inserts an element into the at the specified index. - does not accept `null` as a valid value. allows duplicate elements. - - If `index` is equal to current count of items in the , then the `item` is added to the end of . - - This method is an O(`n`) operation, where `n` is . - + does not accept `null` as a valid value. allows duplicate elements. + + If `index` is equal to current count of items in the , then the `item` is added to the end of . + + This method is an O(`n`) operation, where `n` is . + ]]> - The parameter is less than zero - - -or- - + The parameter is less than zero + + -or- + the parameter is greater than the current count of items in the . The parameter is . @@ -136,19 +136,19 @@ The new value for the element at the specified index. The value can be for reference types. Replaces the element at the specified index. - does not accept `null` as a valid value. allows duplicate elements. - - This method is an O(1) operation. - + does not accept `null` as a valid value. allows duplicate elements. + + This method is an O(1) operation. + ]]> - The parameter is less than zero - - -or- - + The parameter is less than zero + + -or- + the parameter is greater than the current count of items in the . The parameter is . diff --git a/xml/System.Net/IWebProxy.xml b/xml/System.Net/IWebProxy.xml index 791b49d863b..e133d3a2ccd 100644 --- a/xml/System.Net/IWebProxy.xml +++ b/xml/System.Net/IWebProxy.xml @@ -171,12 +171,12 @@ method returns the URI of the proxy server that handles requests to the Internet resource that is specified in the `destination` parameter. If the method returns null or `destination` itself, the proxy is not used to contact the host and the request is passed directly to the server. + The method returns the URI of the proxy server that handles requests to the Internet resource that is specified in the `destination` parameter. If the method returns null or `destination` itself, the proxy is not used to contact the host and the request is passed directly to the server. ## Examples - The following example uses the method to return the URI that the uses to access the Internet resource. + The following example uses the method to return the URI that the uses to access the Internet resource. :::code language="csharp" source="~/snippets/csharp/System.Net/IWebProxy/Credentials/iwebproxy_interface.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IWebProxy/Credentials/iwebproxy_interface.vb" id="Snippet4"::: @@ -235,7 +235,7 @@ method indicates whether to use the proxy server to access the host that is specified in the `host` parameter. If returns `true`, the proxy is not used to contact the host and the request is passed directly to the server. Getting `false` from does not guarantee that the URI is proxied; you still need to call the method to determine this. + The method indicates whether to use the proxy server to access the host that is specified in the `host` parameter. If returns `true`, the proxy is not used to contact the host and the request is passed directly to the server. Getting `false` from does not guarantee that the URI is proxied; you still need to call the method to determine this. diff --git a/xml/System.Net/IWebRequestCreate.xml b/xml/System.Net/IWebRequestCreate.xml index 771f2d89696..ff0d60662c1 100644 --- a/xml/System.Net/IWebRequestCreate.xml +++ b/xml/System.Net/IWebRequestCreate.xml @@ -51,13 +51,13 @@ Provides the base interface for creating instances. - interface defines the method that descendants must use to register with the method. - - Classes that implement the interface can be registered with the class and associated with a specific URI scheme so that the calls the class's method when a URI that matches that scheme is requested. - + interface defines the method that descendants must use to register with the method. + + Classes that implement the interface can be registered with the class and associated with a specific URI scheme so that the calls the class's method when a URI that matches that scheme is requested. + ]]> @@ -110,11 +110,11 @@ Creates a instance. A instance. - method must return an initialized instance of the descendant that is capable of performing a standard request/response transaction for the protocol without needing any protocol-specific fields modified. - + method must return an initialized instance of the descendant that is capable of performing a standard request/response transaction for the protocol without needing any protocol-specific fields modified. + ]]> The request scheme specified in is not supported by this instance. diff --git a/xml/System.Net/NetworkCredential.xml b/xml/System.Net/NetworkCredential.xml index 0f79ee537af..0cd4ccc5eb1 100644 --- a/xml/System.Net/NetworkCredential.xml +++ b/xml/System.Net/NetworkCredential.xml @@ -628,7 +628,7 @@ method to retrieve a object for the specified URI. + The following code example uses the method to retrieve a object for the specified URI. :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/GetCredential/networkcredential_getcredential.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/NetworkCredential/GetCredential/networkcredential_getcredential.vb" id="Snippet1"::: diff --git a/xml/System.Net/OpenReadCompletedEventArgs.xml b/xml/System.Net/OpenReadCompletedEventArgs.xml index 16ccfe7bde2..40acd9e0c1a 100644 --- a/xml/System.Net/OpenReadCompletedEventArgs.xml +++ b/xml/System.Net/OpenReadCompletedEventArgs.xml @@ -122,7 +122,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/OpenWriteCompletedEventArgs.xml b/xml/System.Net/OpenWriteCompletedEventArgs.xml index e1c94a7a410..1b48e477261 100644 --- a/xml/System.Net/OpenWriteCompletedEventArgs.xml +++ b/xml/System.Net/OpenWriteCompletedEventArgs.xml @@ -122,7 +122,7 @@ and properties before using the stream returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the stream returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/ServicePoint.xml b/xml/System.Net/ServicePoint.xml index b7f1fa57837..e7164016485 100644 --- a/xml/System.Net/ServicePoint.xml +++ b/xml/System.Net/ServicePoint.xml @@ -66,7 +66,7 @@ The class handles connections to an Internet resource based on the host information passed in the resource's Uniform Resource Identifier (URI). The initial connection to the resource determines the information that the object maintains, which is then shared by all subsequent requests to that resource. - objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. + objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. @@ -610,7 +610,7 @@ Although a object can make multiple connections t [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - If the object was constructed by calling a overload with a argument, then the property represents the property of the object used. + If the object was constructed by calling a overload with a argument, then the property represents the property of the object used. If the object was constructed from a network host and port, the property contains a string that represents the host and the network port. If the property is set when constructed from a host and port, only objects with the same value can use this object. diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index 82fe9de3769..e1c3fee382b 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -188,7 +188,7 @@ is `true`, the certificate is checked against the certificate authority revocation list, as part of the certificate validation process. Its default value is `false`. + When the is `true`, the certificate is checked against the certificate authority revocation list, as part of the certificate validation process. Its default value is `false`. > [!NOTE] > Since .NET 9, this property maps to on . @@ -710,7 +710,7 @@ method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + The method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. ]]> @@ -786,7 +786,7 @@ method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + The method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. @@ -870,7 +870,7 @@ method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + The method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. ]]> @@ -928,7 +928,7 @@ ## Remarks The property sets the maximum idle time that the object assigns to the property when creating objects. Changes to this value affect only objects that are initialized after the value is changed. - After a object has been idle for the time specified in , it is eligible for garbage collection. A object is idle when the list of connections associated with the object is empty. + After a object has been idle for the time specified in , it is eligible for garbage collection. A object is idle when the list of connections associated with the object is empty. > [!NOTE] > Since .NET 9, this property maps to unless overridden by . However, handlers are not being reused between requests so it doesn't have any meaningful impact. @@ -999,7 +999,7 @@ property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the objects as they become idle. If this limit is set and more distinct instances are requested, will throw. As a result, requests leading to new, distinct endpoints will fail. + When you reduce the property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the objects as they become idle. If this limit is set and more distinct instances are requested, will throw. As a result, requests leading to new, distinct endpoints will fail. > [!NOTE] > This property is only implemented on .NET Framework. @@ -1199,10 +1199,10 @@ For versions of the .NET Framework through the .NET Framework 4.6.2, no default ## Remarks An application can set the property to a method to use for custom validation by the client of the server certificate. When doing custom validation, the `sender` parameter passed to the can be a host string name or an object derived from (, for example) depending on the property. -When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if was passed a parameter of `"https://www.contoso.com/default.html"`, the default behavior is for the client to check the certificate against `www.contoso.com`. +When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if was passed a parameter of `"https://www.contoso.com/default.html"`, the default behavior is for the client to check the certificate against `www.contoso.com`. Despite being a multicast delegate, only the value returned from the last-executed event handler is considered authoritative. -In other words, you can attach multiple delegates, and they all get a callback from . +In other words, you can attach multiple delegates, and they all get a callback from . Each callback returns a value that indicates whether the certificate is accepted or not; however, only the value from the last delegate is respected. > [!NOTE] diff --git a/xml/System.Net/SocketAddress.xml b/xml/System.Net/SocketAddress.xml index 3049846f74e..32c6dceb7c5 100644 --- a/xml/System.Net/SocketAddress.xml +++ b/xml/System.Net/SocketAddress.xml @@ -63,7 +63,7 @@ enumerated value. When the is used to store a serialized , the third and fourth bytes are used to store port number information. The next bytes are used to store the IP address. You can access any information within this underlying byte buffer by referring to its index position; the byte buffer uses zero-based indexing. You can also use the and properties to get the value and the buffer size, respectively. To view any of this information as a string, use the method. + The first 2 bytes of the underlying buffer are reserved for the enumerated value. When the is used to store a serialized , the third and fourth bytes are used to store port number information. The next bytes are used to store the IP address. You can access any information within this underlying byte buffer by referring to its index position; the byte buffer uses zero-based indexing. You can also use the and properties to get the value and the buffer size, respectively. To view any of this information as a string, use the method. @@ -377,7 +377,7 @@ enumerated value that represents the addressing scheme of the current . If you want to view the corresponding string representation of , use the method. + This method gets the enumerated value that represents the addressing scheme of the current . If you want to view the corresponding string representation of , use the method. ]]> @@ -523,7 +523,7 @@ This property gets or sets the specified byte position in the underlying buffer. > [!NOTE] -> Be sure to call before referring to elements in the underlying buffer. Referring to an index that does not exist will cause the to throw an . +> Be sure to call before referring to elements in the underlying buffer. Referring to an index that does not exist will cause the to throw an . ]]> @@ -642,7 +642,7 @@ method returns a string that contains the enumerated value, the size of the underlying buffer of the structure, and the remaining contents of the buffer. + The method returns a string that contains the enumerated value, the size of the underlying buffer of the structure, and the remaining contents of the buffer. ]]> diff --git a/xml/System.Net/SocketPermission.xml b/xml/System.Net/SocketPermission.xml index 19508a1b357..aa5e4af8f82 100644 --- a/xml/System.Net/SocketPermission.xml +++ b/xml/System.Net/SocketPermission.xml @@ -112,7 +112,7 @@ instance is created with the `Unrestricted` value from then the instance passes all demands. Any other value for `state` results in a instance that fails all demands unless a transport address permission is added with . + If the instance is created with the `Unrestricted` value from then the instance passes all demands. Any other value for `state` results in a instance that fails all demands unless a transport address permission is added with . ]]> @@ -380,7 +380,7 @@ and is implemented to support the interface. + The object returned by this method represents the same level of access as the current instance. This method overrides and is implemented to support the interface. ]]> @@ -426,9 +426,9 @@ method reconstructs a instance from an XML encoding defined by the class. + The method reconstructs a instance from an XML encoding defined by the class. - Use the method to encode the instance, including state information, in XML. + Use the method to encode the instance, including state information, in XML. ]]> @@ -477,7 +477,7 @@ and is implemented to support the interface. + The intersection of two permissions is a permission that helps to protect the resources and operations protected by both permissions. Specifically, it represents the minimum permission such that any demand that passes both permissions also passes their intersection. This method overrides and is implemented to support the interface. ]]> @@ -618,9 +618,9 @@ method creates a instance to encode a representation of the instance, including state information, in XML. + The method creates a instance to encode a representation of the instance, including state information, in XML. - Use the method to restore the state information from a instance. + Use the method to restore the state information from a instance. ]]> @@ -667,7 +667,7 @@ is a permission that represents all of the access to connections represented by the current instance as well as the access represented by `target`. Any demand that passes either the current instance or `target` passes their union. This method overrides and is implemented to support the interface. + The result of a call to is a permission that represents all of the access to connections represented by the current instance as well as the access represented by `target`. Any demand that passes either the current instance or `target` passes their union. This method overrides and is implemented to support the interface. ]]> diff --git a/xml/System.Net/SocketPermissionAttribute.xml b/xml/System.Net/SocketPermissionAttribute.xml index 8e77209a2ac..3aafd40356f 100644 --- a/xml/System.Net/SocketPermissionAttribute.xml +++ b/xml/System.Net/SocketPermissionAttribute.xml @@ -208,7 +208,7 @@ method is called by the security system, not by the application code. The security information described by is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run-time and calls . The system uses the returned to enforce the specified security requirements. + The method is called by the security system, not by the application code. The security information described by is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run-time and calls . The system uses the returned to enforce the specified security requirements. ]]> diff --git a/xml/System.Net/TransportContext.xml b/xml/System.Net/TransportContext.xml index a76612e5295..5cf18348a21 100644 --- a/xml/System.Net/TransportContext.xml +++ b/xml/System.Net/TransportContext.xml @@ -57,7 +57,7 @@ is the only class derived from class that can potentially use IWA. The class does only FTP clear text authentication. The class doesn't perform any authentication. - There are several ways an application may get a instance. An application that uses can get the using the property. An application that uses can get a using the or methods. + There are several ways an application may get a instance. An application that uses can get the using the property. An application that uses can get a using the or methods. ]]> @@ -161,7 +161,7 @@ ## Remarks The possible values for the `kind` parameter are or . - If an application attempts to retrieve the channel binding token (CBT) from the property using the method and the is not , then the will throw . The overrides the method with an internal implementation + If an application attempts to retrieve the channel binding token (CBT) from the property using the method and the is not , then the will throw . The overrides the method with an internal implementation ]]> diff --git a/xml/System.Net/UploadDataCompletedEventArgs.xml b/xml/System.Net/UploadDataCompletedEventArgs.xml index 4069b08d939..b6629de0db8 100644 --- a/xml/System.Net/UploadDataCompletedEventArgs.xml +++ b/xml/System.Net/UploadDataCompletedEventArgs.xml @@ -115,7 +115,7 @@ and properties before using the data returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadFileCompletedEventArgs.xml b/xml/System.Net/UploadFileCompletedEventArgs.xml index 944c5c6923d..e8e39ec4084 100644 --- a/xml/System.Net/UploadFileCompletedEventArgs.xml +++ b/xml/System.Net/UploadFileCompletedEventArgs.xml @@ -115,7 +115,7 @@ and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadProgressChangedEventArgs.xml b/xml/System.Net/UploadProgressChangedEventArgs.xml index c6aa9a7adc9..6fe846c57ce 100644 --- a/xml/System.Net/UploadProgressChangedEventArgs.xml +++ b/xml/System.Net/UploadProgressChangedEventArgs.xml @@ -109,9 +109,9 @@ and . + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. ]]> @@ -168,9 +168,9 @@ and . + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. ]]> @@ -229,9 +229,9 @@ ## Remarks To determine the number of bytes already received, use the property. - Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. ]]> @@ -290,9 +290,9 @@ ## Remarks To determine the number of bytes already sent, use the property. - Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. ]]> diff --git a/xml/System.Net/UploadStringCompletedEventArgs.xml b/xml/System.Net/UploadStringCompletedEventArgs.xml index 112711b8ea2..42ffbe7d3b9 100644 --- a/xml/System.Net/UploadStringCompletedEventArgs.xml +++ b/xml/System.Net/UploadStringCompletedEventArgs.xml @@ -122,7 +122,7 @@ and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadValuesCompletedEventArgs.xml b/xml/System.Net/UploadValuesCompletedEventArgs.xml index e69c01ac975..6a3568e44aa 100644 --- a/xml/System.Net/UploadValuesCompletedEventArgs.xml +++ b/xml/System.Net/UploadValuesCompletedEventArgs.xml @@ -102,7 +102,7 @@ and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. ]]> diff --git a/xml/System.Net/WebClient.xml b/xml/System.Net/WebClient.xml index be0597573b5..554bc4cfd9d 100644 --- a/xml/System.Net/WebClient.xml +++ b/xml/System.Net/WebClient.xml @@ -72,7 +72,7 @@ The class provides common methods for sending data to or receiving data from any local, intranet, or Internet resource identified by a URI. - The class uses the class to provide access to resources. instances can access data with any descendant registered with the method. + The class uses the class to provide access to resources. instances can access data with any descendant registered with the method. > [!NOTE] > By default, .NET Framework supports URIs that begin with `http:`, `https:`, `ftp:`, and `file:` scheme identifiers. @@ -81,35 +81,35 @@ |Method|Description| |------------|-----------------| -||Retrieves a used to send data to the resource.| -||Retrieves a used to send data to the resource, without blocking the calling thread.| -||Sends a byte array to the resource and returns a array containing any response.| -||Sends a array to the resource, without blocking the calling thread.| -||Sends a local file to the resource and returns a array containing any response.| -||Sends a local file to the resource, without blocking the calling thread.| -||Sends a to the resource and returns a array containing any response.| -||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| -||Sends a to the resource and returns a containing any response.| -||Sends a to the resource, without blocking the calling thread.| +||Retrieves a used to send data to the resource.| +||Retrieves a used to send data to the resource, without blocking the calling thread.| +||Sends a byte array to the resource and returns a array containing any response.| +||Sends a array to the resource, without blocking the calling thread.| +||Sends a local file to the resource and returns a array containing any response.| +||Sends a local file to the resource, without blocking the calling thread.| +||Sends a to the resource and returns a array containing any response.| +||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| +||Sends a to the resource and returns a containing any response.| +||Sends a to the resource, without blocking the calling thread.| The following table describes methods for downloading data from a resource. |Method|Description| |------------|-----------------| -||Returns the data from a resource as a .| -||Returns the data from a resource, without blocking the calling thread.| -||Downloads data from a resource and returns a array.| -||Downloads data from a resource and returns a array, without blocking the calling thread.| -||Downloads data from a resource to a local file.| -||Downloads data from a resource to a local file, without blocking the calling thread.| -||Downloads a from a resource and returns a .| -||Downloads a from a resource, without blocking the calling thread.| +||Returns the data from a resource as a .| +||Returns the data from a resource, without blocking the calling thread.| +||Downloads data from a resource and returns a array.| +||Downloads data from a resource and returns a array, without blocking the calling thread.| +||Downloads data from a resource to a local file.| +||Downloads data from a resource to a local file, without blocking the calling thread.| +||Downloads a from a resource and returns a .| +||Downloads a from a resource, without blocking the calling thread.| - You can use the method to attempt to cancel asynchronous operations. + You can use the method to attempt to cancel asynchronous operations. - A instance does not send optional HTTP headers by default. If your request requires an optional header, you must add the header to the collection. For example, to retain queries in the response, you must add a user-agent header. Also, servers may return 500 (Internal Server Error) if the user agent header is missing. + A instance does not send optional HTTP headers by default. If your request requires an optional header, you must add the header to the collection. For example, to retain queries in the response, you must add a user-agent header. Also, servers may return 500 (Internal Server Error) if the user agent header is missing. - is set to `true` in instances. + is set to `true` in instances. ## Examples The following code example takes the URI of a resource, retrieves it, and displays the response. @@ -178,7 +178,7 @@ ## Remarks - The parameterless constructor creates a new instance of the class. The default HTTP method is GET. The default FTP method is RETR. The default is . The default value of is `true`. + The parameterless constructor creates a new instance of the class. The default HTTP method is GET. The default FTP method is RETR. The default is . The default value of is `true`. ## Examples The following code example creates a instance and then uses it to download data from a server and display it on the system console, to download data from a server and write it to a file, and to upload form values to a server and receive the response. @@ -488,12 +488,12 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - If an operation is pending, this method calls on the underlying . + If an operation is pending, this method calls on the underlying . > [!NOTE] - > Starting in .NET Core 2.0, doesn't cancel the request immediately if the response has started to fetch. For optimum cancellation behavior, use the class instead of . + > Starting in .NET Core 2.0, doesn't cancel the request immediately if the response has started to fetch. For optimum cancellation behavior, use the class instead of . - When you call , your application still receives the completion event associated with the operation. For example, when you call to cancel a operation, if you have specified an event handler for the event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the property on the base class of in the event data object passed to the event handler. + When you call , your application still receives the completion event associated with the operation. For example, when you call to cancel a operation, if you have specified an event handler for the event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the property on the base class of in the event data object passed to the event handler. If no asynchronous operation is in progress, this method does nothing. @@ -565,9 +565,9 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the authentication credentials used to access a resource on a host. In most client-side scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. + The property contains the authentication credentials used to access a resource on a host. In most client-side scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. - If the class is being used in a middle tier application, such as an ASP.NET application, the belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. + If the class is being used in a middle tier application, such as an ASP.NET application, the belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. For security reasons, when automatically following redirects, store the credentials that you want to be included in the redirect in a and assign it to this property. This property will automatically be set to `null` upon redirection if it contains anything except a . Having this property value be automatically set to `null` under those conditions prevents credentials from being sent to any unintended destination. @@ -648,9 +648,9 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -727,9 +727,9 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -810,13 +810,13 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in `address`. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. + This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -896,13 +896,13 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in `address`. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. + This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -972,7 +972,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous data download operation completes. Asynchronous data downloads are started by calling the methods. + This event is raised each time an asynchronous data download operation completes. Asynchronous data downloads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -1064,11 +1064,11 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the data resource has been downloaded. + This operation will not block. The returned object will complete after the data resource has been downloaded. This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1144,11 +1144,11 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the data resource has been downloaded. + This operation will not block. The returned object will complete after the data resource has been downloaded. This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1229,9 +1229,9 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1317,9 +1317,9 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1422,11 +1422,11 @@ This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the file is available, add an event handler to the event. - This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. + This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1517,11 +1517,11 @@ This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the file is available, add an event handler to the event. - This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. + This method does not block the calling thread while the resource is being downloaded. To block while waiting for the download to complete, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1600,7 +1600,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous file download operation completes. Asynchronous file downloads are started by calling the methods. + This event is raised each time an asynchronous file download operation completes. Asynchronous file downloads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -1690,9 +1690,9 @@ This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1779,9 +1779,9 @@ This method downloads the resource at the URI specified by in the `address` parameter. When the download completes successfully, the downloaded file is named `fileName` on the local computer. The file is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1864,9 +1864,9 @@ |Method|Description| |------------|-----------------| -||Downloads data from a resource and returns a array, without blocking the calling thread.| -||Downloads data from a resource to a local file, without blocking the calling thread.| -||Returns the data from a resource, without blocking the calling thread.| +||Downloads data from a resource and returns a array, without blocking the calling thread.| +||Downloads data from a resource to a local file, without blocking the calling thread.| +||Returns the data from a resource, without blocking the calling thread.| The is the delegate for this event. The class provides the event handler with event data. @@ -1960,9 +1960,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2039,9 +2039,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2128,11 +2128,11 @@ internal class MyWebClient : WebClientProtocol The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2214,11 +2214,11 @@ internal class MyWebClient : WebClientProtocol The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2290,7 +2290,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous operation to download a resource as a string completes. These operations are started by calling the methods. + This event is raised each time an asynchronous operation to download a resource as a string completes. These operations are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -2382,13 +2382,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2461,13 +2461,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2537,9 +2537,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The and methods use this property to convert the specified string to a array before uploading the string. For additional information, see the method. + The and methods use this property to convert the specified string to a array before uploading the string. For additional information, see the method. - When a string is downloaded using the or methods, uses the returned by this to convert the downloaded array into a string. For additional information, see the method. + When a string is downloaded using the or methods, uses the returned by this to convert the downloaded array into a string. For additional information, see the method. @@ -2606,9 +2606,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method copies the existing , , and method to the newly created object. + This method copies the existing , , and method to the newly created object. - This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. Derived classes should call the base class implementation of to ensure the method works as expected. + This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. Derived classes should call the base class implementation of to ensure the method works as expected. @@ -2684,7 +2684,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The object returned by this method is obtained by calling the method on the specified object. + The object returned by this method is obtained by calling the method on the specified object. This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. @@ -2754,7 +2754,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The object returned by this method is obtained by calling the method on the specified object. + The object returned by this method is obtained by calling the method on the specified object. This method can be called only by classes that inherit from . It is provided to give inheritors access to the underlying object. @@ -2858,7 +2858,7 @@ internal class MyWebClient : WebClientProtocol ## Examples - The following code example uses the collection to set the HTTP `Content-Type` header to `application/x-www-form-urlencoded,` to notify the server that form data is attached to the post. + The following code example uses the collection to set the HTTP `Content-Type` header to `application/x-www-form-urlencoded,` to notify the server that form data is attached to the post. [!code-cpp[WebClient_UpLoadData_Headers#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData_Headers/CPP/webclient_uploaddata_headers.cpp#2)] [!code-csharp[WebClient_UpLoadData_Headers#2](~/snippets/csharp/System.Net/WebClient/Headers/webclient_uploaddata_headers.cs#2)] @@ -2970,7 +2970,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3042,7 +3042,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3114,7 +3114,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3186,7 +3186,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3258,7 +3258,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3330,7 +3330,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3402,7 +3402,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3474,7 +3474,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3546,7 +3546,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3615,7 +3615,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3687,7 +3687,7 @@ internal class MyWebClient : WebClientProtocol Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -3821,20 +3821,20 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. > [!NOTE] -> You must call when finished with the to avoid running out of system resources. +> You must call when finished with the to avoid running out of system resources. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example opens the resource identified by `uriString` and displays the results on the system console. The returned by is closed when the data has been read. + The following code example opens the resource identified by `uriString` and displays the results on the system console. The returned by is closed when the data has been read. [!code-cpp[WebClient_OpenRead#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenRead/CPP/webclient_openread.cpp#1)] [!code-csharp[WebClient_OpenRead#1](~/snippets/csharp/System.Net/WebClient/OpenRead/webclient_openread.cs#1)] @@ -3902,14 +3902,14 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. > [!NOTE] -> You must call when finished with the to avoid running out of system resources. +> You must call when finished with the to avoid running out of system resources. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3994,13 +3994,13 @@ internal class MyWebClient : WebClientProtocol This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. + This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4087,13 +4087,13 @@ internal class MyWebClient : WebClientProtocol This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. + This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4169,7 +4169,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous operation to open a stream containing a resource completes. These operations are started by calling the methods. + This event is raised each time an asynchronous operation to open a stream containing a resource completes. These operations are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -4261,16 +4261,16 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4349,16 +4349,16 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a readable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4443,9 +4443,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4453,7 +4453,7 @@ internal class MyWebClient : WebClientProtocol > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example reads data from the command line and uses to obtain a stream for writing the data. The returned by is closed after the data is sent. + The following code example reads data from the command line and uses to obtain a stream for writing the data. The returned by is closed after the data is sent. [!code-cpp[WebClient_OpenWrite2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenWrite2/CPP/webclient_openwrite2.cpp#1)] [!code-csharp[WebClient_OpenWrite2#1](~/snippets/csharp/System.Net/WebClient/OpenWrite/webclient_openwrite2.cs#1)] @@ -4527,9 +4527,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4609,17 +4609,17 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a writable stream that is used to send data to a resource. The underlying request is made with the method specified in the `method` parameter. The data is sent to the server when you close the stream. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method returns a writable stream that is used to send data to a resource. The underlying request is made with the method specified in the `method` parameter. The data is sent to the server when you close the stream. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not specify an absolute address, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute address, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example reads data from the command line and uses to obtain a stream used to write the data. The returned by must be closed to send the data. + The following code example reads data from the command line and uses to obtain a stream used to write the data. The returned by must be closed to send the data. [!code-cpp[WebClient_OpenWrite#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_OpenWrite/CPP/webclient_openwrite.cpp#1)] [!code-csharp[WebClient_OpenWrite#1](~/snippets/csharp/System.Net/WebClient/OpenWrite/webclient_openwrite.cs#1)] @@ -4697,9 +4697,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. + The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4783,9 +4783,9 @@ internal class MyWebClient : WebClientProtocol This method retrieves a writable stream that is used to send data to a resource. The stream is retrieved using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. When you close the stream, the thread blocks until the request is sent to `address` and a response is received. - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. + This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4868,9 +4868,9 @@ internal class MyWebClient : WebClientProtocol This method retrieves a writable stream that is used to send data to a resource. The stream is retrieved using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. When you close the stream, the thread blocks until the request is sent to `address` and a response is received. - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. + This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4949,11 +4949,11 @@ internal class MyWebClient : WebClientProtocol If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. + This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5023,7 +5023,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous operation to open a stream that is used to send data to a resource completes. These operations are started by calling the methods. + This event is raised each time an asynchronous operation to open a stream that is used to send data to a resource completes. These operations are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -5115,16 +5115,16 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5198,16 +5198,16 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5290,18 +5290,18 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5385,18 +5385,18 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. + This operation will not block. The returned object will complete after the a writable stream to the data resource has been opened. This method does not block the calling thread while the stream is opening. This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5615,7 +5615,7 @@ internal class MyWebClient : WebClientProtocol ## Examples - The following code example downloads and displays the returned by a server. + The following code example downloads and displays the returned by a server. [!code-cpp[WebClient_BaseAddress_ResponseHeaders#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_BaseAddress_ResponseHeaders/CPP/webclient_baseaddress_responseheaders.cpp#2)] [!code-csharp[WebClient_BaseAddress_ResponseHeaders#2](~/snippets/csharp/System.Net/WebClient/BaseAddress/webclient_baseaddress_responseheaders.cs#2)] @@ -5690,19 +5690,19 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a data buffer to a resource. + The method sends a data buffer to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example converts a string entered from the console to a array and posts the array to the specified server using . Any response from the server is displayed to the console. + The following code example converts a string entered from the console to a array and posts the array to the specified server using . Any response from the server is displayed to the console. [!code-cpp[WebClient_UpLoadData2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData2/CPP/webclient_uploaddata2.cpp#1)] [!code-csharp[WebClient_UpLoadData2#1](~/snippets/csharp/System.Net/WebClient/UploadData/webclient_uploaddata2.cs#1)] @@ -5786,13 +5786,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a data buffer to a resource. + The method sends a data buffer to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5880,19 +5880,19 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - The method sends the content of `data` to the server without encoding it. + The method sends the content of `data` to the server without encoding it. If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example converts a string entered from the console into a byte array and posts the array to the specified server using . Any response from the server is displayed to the console. + The following code example converts a string entered from the console into a byte array and posts the array to the specified server using . Any response from the server is displayed to the console. [!code-cpp[WebClient_UpLoadData_Headers#2](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadData_Headers/CPP/webclient_uploaddata_headers.cpp#2)] [!code-csharp[WebClient_UpLoadData_Headers#2](~/snippets/csharp/System.Net/WebClient/Headers/webclient_uploaddata_headers.cs#2)] @@ -5980,13 +5980,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a data buffer to a resource using the HTTP method specified in the `method` parameter, and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - The method sends the content of `data` to the server without encoding it. + The method sends the content of `data` to the server without encoding it. If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6080,11 +6080,11 @@ internal class MyWebClient : WebClientProtocol This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. To receive notification when the data upload completes, add an event handler to the event. - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6178,11 +6178,11 @@ internal class MyWebClient : WebClientProtocol This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. To receive notification when the data upload completes, add an event handler to the event. - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6277,11 +6277,11 @@ internal class MyWebClient : WebClientProtocol This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. To receive notification when the data upload completes, add an event handler to the event. - This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the data is being sent. To send data and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6355,7 +6355,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous data upload operation completes. Asynchronous data uploads are started by calling the methods. + This event is raised each time an asynchronous data upload operation completes. Asynchronous data uploads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -6449,13 +6449,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. + This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6535,13 +6535,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. + This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6631,13 +6631,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. + This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6725,13 +6725,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. + This operation will not block. The returned object will complete after the a data buffer has been uploaded to the resource. This method sends a data buffer to a resource. The data buffer is sent asynchronously using thread resources that are automatically allocated from the thread pool. The data is not encoded. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6815,25 +6815,25 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. + The method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. + This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. + The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. [!code-cpp[WebClient_UpLoadFile#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadFile/CPP/webclient_uploadfile.cpp#1)] [!code-csharp[WebClient_UpLoadFile#1](~/snippets/csharp/System.Net/WebClient/UploadFile/webclient_uploadfile.cs#1)] [!code-vb[WebClient_UpLoadFile#1](~/snippets/visualbasic/System.Net/WebClient/UploadFile/webclient_uploadfile.vb#1)] - The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. + The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. [!code-aspx-csharp[NCLWebClientAsp#1](~/snippets/csharp/System.Net/WebClient/UploadFile/fileuploadercs.aspx#1)] [!code-aspx-vb[NCLWebClientAsp#1](~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebClientAsp/VB/fileuploadervb.aspx#1)] @@ -6924,13 +6924,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. + The method sends a local file to a resource. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. - This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. + This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7026,23 +7026,23 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. + When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. + The following code example uploads the specified file to the specified URI using . Any response returned by the server is displayed on the console. [!code-cpp[WebClient_UpLoadFile2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UpLoadFile2/CPP/webclient_uploadfile2.cpp#1)] [!code-csharp[WebClient_UpLoadFile2#1](~/snippets/csharp/System.Net/WebClient/UploadFile/webclient_uploadfile2.cs#1)] [!code-vb[WebClient_UpLoadFile2#1](~/snippets/visualbasic/System.Net/WebClient/UploadFile/webclient_uploadfile2.vb#1)] - The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. + The following code example shows an ASP.NET page that can accept posted files and is suitable for use with the method. The page must reside on a Web server. Its address provides the value for the `address` parameter of the method. [!code-aspx-csharp[NCLWebClientAsp#1](~/snippets/csharp/System.Net/WebClient/UploadFile/fileuploadercs.aspx#1)] [!code-aspx-vb[NCLWebClientAsp#1](~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebClientAsp/VB/fileuploadervb.aspx#1)] @@ -7137,11 +7137,11 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. + When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7243,11 +7243,11 @@ internal class MyWebClient : WebClientProtocol The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the file upload completes, add an event handler to the event. - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7353,11 +7353,11 @@ internal class MyWebClient : WebClientProtocol The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the file upload completes, add an event handler to the event. - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7466,11 +7466,11 @@ internal class MyWebClient : WebClientProtocol The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the file upload completes, add an event handler to the event. - This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the file is being sent. To send a file and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7558,7 +7558,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous file upload operation completes. Asynchronous file uploads are started by calling the methods. + This event is raised each time an asynchronous file upload operation completes. Asynchronous file uploads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -7652,11 +7652,11 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7748,11 +7748,11 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7854,11 +7854,11 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7960,11 +7960,11 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the file has been uploaded to the resource. The file is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8056,9 +8056,9 @@ internal class MyWebClient : WebClientProtocol |Method|Description| |------------|-----------------| -||Sends a array to the resource, without blocking the calling thread.| -||Sends a local file to the resource, without blocking the calling thread.| -||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| +||Sends a array to the resource, without blocking the calling thread.| +||Sends a local file to the resource, without blocking the calling thread.| +||Sends a to the resource and returns a array containing any response, without blocking the calling thread.| The is the delegate for this event. The class provides the event handler with event data. @@ -8147,9 +8147,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8237,9 +8237,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8324,9 +8324,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8420,9 +8420,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8516,11 +8516,11 @@ internal class MyWebClient : WebClientProtocol This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8614,11 +8614,11 @@ internal class MyWebClient : WebClientProtocol This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8717,11 +8717,11 @@ internal class MyWebClient : WebClientProtocol This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8799,7 +8799,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous string upload operation completes. Asynchronous string uploads are started by calling the methods. + This event is raised each time an asynchronous string upload operation completes. Asynchronous string uploads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -8893,13 +8893,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8977,13 +8977,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9071,13 +9071,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9169,13 +9169,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the string has been uploaded to the resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9263,13 +9263,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". + If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9277,7 +9277,7 @@ internal class MyWebClient : WebClientProtocol > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. + The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. [!code-cpp[WebClient_UploadValues#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UploadValues/CPP/webclient_uploadvalues.cpp#1)] [!code-csharp[WebClient_UploadValues#1](~/snippets/csharp/System.Net/WebClient/UploadValues/webclient_uploadvalues.cs#1)] @@ -9369,13 +9369,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". + If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9473,19 +9473,19 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. + If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples - The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. + The following code example gathers information from the user (name, age, and address) and posts the values to the server using . Any response from the server is displayed on the console. [!code-cpp[WebClient_UploadValues2#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_UploadValues2/CPP/webclient_uploadvalues2.cpp#1)] [!code-csharp[WebClient_UploadValues2#1](~/snippets/csharp/System.Net/WebClient/UploadValues/webclient_uploadvalues2.cs#1)] @@ -9581,13 +9581,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. + The method sends a to a resource using the method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. + If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9689,11 +9689,11 @@ internal class MyWebClient : WebClientProtocol This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9785,17 +9785,17 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. + This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9892,17 +9892,17 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. + This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. - This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. + This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9980,7 +9980,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous upload of a object's data completes. These uploads are started by calling the methods. + This event is raised each time an asynchronous upload of a object's data completes. These uploads are started by calling the methods. The is the delegate for this event. The class provides the event handler with event data. @@ -10059,15 +10059,15 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10155,15 +10155,15 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10261,15 +10261,15 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10371,15 +10371,15 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. + This operation will not block. The returned object will complete after the name/value collection has been uploaded to the resource. The name/value collection is sent asynchronously using thread resources that are automatically allocated from the thread pool. - In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. + In .NET Framework, you can cancel asynchronous operations that have not completed by calling the method. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10535,7 +10535,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This event is raised each time an asynchronous operation used to write data to a resource using a write stream is closed. These operations result from calls to the methods. + This event is raised each time an asynchronous operation used to write data to a resource using a write stream is closed. These operations result from calls to the methods. The is the delegate for this event. The class provides the event handler with event data. diff --git a/xml/System.Net/WebException.xml b/xml/System.Net/WebException.xml index 4ec19bf4728..26d533db60f 100644 --- a/xml/System.Net/WebException.xml +++ b/xml/System.Net/WebException.xml @@ -146,7 +146,7 @@ class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . + The parameterless constructor initializes a new instance of the class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . @@ -214,7 +214,7 @@ instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . + The instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . @@ -350,7 +350,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. @@ -421,7 +421,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . @@ -630,12 +630,12 @@ sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. + Some Internet protocols, such as HTTP, return otherwise valid responses indicating that an error has occurred at the protocol level. When the response to an Internet request indicates an error, sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. ## Examples - The following example checks the property and prints to the console the and of the underlying instance. + The following example checks the property and prints to the console the and of the underlying instance. :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebException/Response/webexception_status_response.vb" id="Snippet1"::: @@ -699,7 +699,7 @@ ## Remarks The property indicates the reason for the . - The value of is one of the values. + The value of is one of the values. > [!WARNING] > The error is not returned to Windows 8.x Store apps. @@ -707,7 +707,7 @@ ## Examples - The following example checks the property and prints to the console the and of the underlying instance. + The following example checks the property and prints to the console the and of the underlying instance. :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebException/Response/webexception_status_response.vb" id="Snippet1"::: diff --git a/xml/System.Net/WebHeaderCollection.xml b/xml/System.Net/WebHeaderCollection.xml index a0997ddf821..45b4768c5d6 100644 --- a/xml/System.Net/WebHeaderCollection.xml +++ b/xml/System.Net/WebHeaderCollection.xml @@ -103,7 +103,7 @@ class is generally accessed through or . + The class is generally accessed through or . On .NET Framework, some common headers are considered restricted and are either exposed directly by the API (such as `Content-Type`) or protected by the system and cannot be changed. This does *not* apply to .NET Core and .NET 5+, where none of the headers are restricted. @@ -333,7 +333,7 @@ If the header specified in `header` is already present in the collection, the value part of the `header` is concatenated with the existing value. ## Examples - The following example adds a name/value pair to a using the Method. + The following example adds a name/value pair to a using the Method. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Add/webheadercollection_add.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Add/webheadercollection_add.vb" id="Snippet1"::: @@ -422,7 +422,7 @@ method inserts a new header into the list of header name/value pairs. + If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. @@ -491,7 +491,7 @@ method inserts a new header into the list of header name/value pairs. + If the specified header does not exist, the method inserts a new header into the list of header name/value pairs. If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. @@ -568,14 +568,14 @@ method inserts a new header into the list of header name/value pairs. + If the header specified in `name` does not exist, the method inserts a new header into the list of header name/value pairs. If the header specified in `name` is already present, `value` is added to the existing comma-separated list of values associated with `name`. ## Examples - The following example adds a name/value pair to a using the Method. + The following example adds a name/value pair to a using the Method. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Add/webheadercollection_add.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Add/webheadercollection_add.vb" id="Snippet1"::: @@ -662,7 +662,7 @@ method adds a header to the collection without checking whether the header is on the restricted header list. + The method adds a header to the collection without checking whether the header is on the restricted header list. > [!NOTE] > The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. @@ -926,7 +926,7 @@ method to retrieve a header value in a . + The following code example uses the method to retrieve a header value in a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: @@ -1111,7 +1111,7 @@ to get a header name in a . + The following code example uses to get a header name in a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: @@ -1265,7 +1265,7 @@ returns the contents of the specified header as an array. + returns the contents of the specified header as an array. ]]> @@ -1331,12 +1331,12 @@ returns the contents of the specified header as an array. + returns the contents of the specified header as an array. ## Examples - The following example uses the method to retrieve an array of values for each header in the . + The following example uses the method to retrieve an array of values for each header in the . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/GetValues/webheadercollection_getvalues_1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/GetValues/webheadercollection_getvalues_1.vb" id="Snippet1"::: @@ -1415,7 +1415,7 @@ method returns `true` to indicate that a header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: + The method returns `true` to indicate that a header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: - Accept @@ -1515,7 +1515,7 @@ method returns `true` to indicate that a request or response header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: + The method returns `true` to indicate that a request or response header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: - Accept @@ -1901,7 +1901,7 @@ deletes the specified header from the collection. If the specified header does not exist, the method does nothing. + deletes the specified header from the collection. If the specified header does not exist, the method does nothing. ]]> @@ -1959,7 +1959,7 @@ deletes the specified header from the collection. If the specified header does not exist, the method does nothing. + deletes the specified header from the collection. If the specified header does not exist, the method does nothing. ]]> @@ -2024,12 +2024,12 @@ deletes the specified header from the collection. If the specified header does not exist, the method returns. + deletes the specified header from the collection. If the specified header does not exist, the method returns. ## Examples - The following example uses the method to remove a header from the . After the header is removed, this example prints all existing headers to the screen to prove that it has been removed. + The following example uses the method to remove a header from the . After the header is removed, this example prints all existing headers to the screen to prove that it has been removed. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Remove/webheadercollection_remove.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Remove/webheadercollection_remove.vb" id="Snippet1"::: @@ -2110,7 +2110,7 @@ method inserts a new header into the list of header name/value pairs. + If the header specified in the header does not exist, the method inserts a new header into the list of header name/value pairs. If the header specified in `header` is already present, `value` replaces the existing value. @@ -2179,7 +2179,7 @@ method inserts a new header into the list of header name/value pairs. + If the header specified in the header does not exist, the method inserts a new header into the list of header name/value pairs. If the header specified in `header` is already present, `value` replaces the existing value. @@ -2256,14 +2256,14 @@ method inserts a new header into the list of header name/value pairs. + If the header specified in the header does not exist, the method inserts a new header into the list of header name/value pairs. If the header specified in `header` is already present, `value` replaces the existing value. ## Examples - The following example uses the method to set the value of an existing header. + The following example uses the method to set the value of an existing header. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Set/webheadercollection_set.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/Set/webheadercollection_set.vb" id="Snippet1"::: diff --git a/xml/System.Net/WebPermission.xml b/xml/System.Net/WebPermission.xml index 34e6e30937b..a12792f2bb0 100644 --- a/xml/System.Net/WebPermission.xml +++ b/xml/System.Net/WebPermission.xml @@ -62,22 +62,22 @@ - No parameters. The default is . -- A . Specify either to allow any URI to be used in the target class, or to allow access only to URIs that you specify through the use of the method. +- A . Specify either to allow any URI to be used in the target class, or to allow access only to URIs that you specify through the use of the method. - A value and a URI string. The specified URI has permissions granted by the value. - A specifier and URI regular expression. - The and hold the URIs to which you have granted access permission. To add a URI to either of these lists, use . If you pass as the parameter, the URI will be added to the . will allow connections to your target class with URIs matching the . + The and hold the URIs to which you have granted access permission. To add a URI to either of these lists, use . If you pass as the parameter, the URI will be added to the . will allow connections to your target class with URIs matching the . > [!CAUTION] -> To deny access to an Internet resource, you must deny access to all the possible paths to that resource. This requires calling with state parameter set to . A better approach is to allow access to the specific resource only. For more information about this subject, refer to the [Using the Deny Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/hk3b9142(v=vs.100)) topic. +> To deny access to an Internet resource, you must deny access to all the possible paths to that resource. This requires calling with state parameter set to . A better approach is to allow access to the specific resource only. For more information about this subject, refer to the [Using the Deny Method](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/hk3b9142(v=vs.100)) topic. > [!NOTE] > You need to deny access using only the resource canonical path. There is no need to use all the path's syntactical variations. > [!NOTE] -> User name and default port information is stripped from the before the comparison with the regular expression argument that is supplied to the constructor. If the regular expression contains user information or the default port number, then all incoming s will fail to match the regular expression. +> User name and default port information is stripped from the before the comparison with the regular expression argument that is supplied to the constructor. If the regular expression contains user information or the default port number, then all incoming s will fail to match the regular expression. ]]> @@ -173,7 +173,7 @@ or , respectively yielding fully restricted or fully unrestricted access to all security variables. If you specify , then you can give access to individual URIs using . + The value of the `state` parameter is either or , respectively yielding fully restricted or fully unrestricted access to all security variables. If you specify , then you can give access to individual URIs using . ]]> @@ -273,7 +273,7 @@ > It is recommended that you create `uriRegex` using the , , and flags. > [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. +> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. ]]> @@ -320,10 +320,10 @@ This property gets a list of local resources permitted by this . The class to which you have applied only has permission to receive an incoming connection to local resources found in this list. > [!NOTE] -> You can add URIs to this list using . +> You can add URIs to this list using . > [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. +> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. ]]> @@ -382,13 +382,13 @@ as the , use to permit the use of `uriString` in the target class. The way that `uriString` can be used by the target class is specified by `access`. Specify as the access parameter to add the URI specified by the `uriString` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. + If you have specified as the , use to permit the use of `uriString` in the target class. The way that `uriString` can be used by the target class is specified by `access`. Specify as the access parameter to add the URI specified by the `uriString` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. > [!NOTE] -> Calling on will have no effect, because permission is granted to all URIs. +> Calling on will have no effect, because permission is granted to all URIs. > [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. +> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. ]]> @@ -439,16 +439,16 @@ as the , use to allow the use of `uriRegex` in the target class. Specify as the `access` parameter to add the URI specified by the `uriRegex` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. + If you have specified as the , use to allow the use of `uriRegex` in the target class. Specify as the `access` parameter to add the URI specified by the `uriRegex` parameter to the list of URI accept strings, or specify as the access parameter to add the URI to the list of URI connect strings. > [!NOTE] -> Calling on an instance will have no effect as permission is granted to all URIs. +> Calling on an instance will have no effect as permission is granted to all URIs. > [!NOTE] > It is recommended that you create `uriRegex` using the , , and flags. > [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. +> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. ]]> @@ -496,10 +496,10 @@ This property gets a list of remote resources that are permitted by this . The class to which you have applied only has permission to connect with resources found in this list. > [!NOTE] -> You can add URIs to this list using . +> You can add URIs to this list using . > [!NOTE] -> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. +> A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. ]]> @@ -544,7 +544,7 @@ returned by this method represents the same access to resources as the original . This method overrides and is implemented to support the interface. + The returned by this method represents the same access to resources as the original . This method overrides and is implemented to support the interface. ]]> @@ -590,9 +590,9 @@ method reconstructs a from an XML encoding that is defined by the class. + The method reconstructs a from an XML encoding that is defined by the class. - Use the method to XML-encode the , including state information. + Use the method to XML-encode the , including state information. ]]> @@ -643,9 +643,9 @@ returns a that contains those permissions that are common in both `target` and the current instance. + returns a that contains those permissions that are common in both `target` and the current instance. - This method overrides and is implemented to support the interface. + This method overrides and is implemented to support the interface. ]]> @@ -695,7 +695,7 @@ specifies a set of associated resources that is wholly contained by the `target` parameter, then the current is a subset of `target`. This method overrides and is implemented to support the interface. + If the current specifies a set of associated resources that is wholly contained by the `target` parameter, then the current is a subset of `target`. This method overrides and is implemented to support the interface. ]]> @@ -748,7 +748,7 @@ If is , then the target class can use all URIs. Otherwise, specific permission must be given for any URI you want to use with the target class. > [!NOTE] -> Use to add a URI and specify its permissions. +> Use to add a URI and specify its permissions. ]]> @@ -793,7 +793,7 @@ method to restore the state information from a . + Use the method to restore the state information from a . ]]> @@ -841,7 +841,7 @@ returns a that contains all the permissions in both `target` and the current instance. + returns a that contains all the permissions in both `target` and the current instance. ]]> diff --git a/xml/System.Net/WebPermissionAttribute.xml b/xml/System.Net/WebPermissionAttribute.xml index b3f93109f34..0c447a8b550 100644 --- a/xml/System.Net/WebPermissionAttribute.xml +++ b/xml/System.Net/WebPermissionAttribute.xml @@ -58,7 +58,7 @@ allows you to declaratively specify which URI strings and regular expression strings your class can use. - The security information specified in the is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses this information at run time. The passed to the constructor determines the allowable targets. The system uses the returned by the method to convert the security information of the attribute target to a serializable form stored in metadata. + The security information specified in the is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses this information at run time. The passed to the constructor determines the allowable targets. The system uses the returned by the method to convert the security information of the attribute target to a serializable form stored in metadata. > [!NOTE] > is used only for [Declarative Security](https://msdn.microsoft.com/library/97e21efd-6e89-4115-90d5-ad239513dad8). For [Imperative Security](https://msdn.microsoft.com/library/15aab1e1-6b7d-41ad-b102-c1ed7bedea27), use the corresponding . @@ -155,7 +155,7 @@ to your class, this property specifies what URI string will be accepted for use within your class. This permission is applied when the security system calls . This property is write-once. + When applying to your class, this property specifies what URI string will be accepted for use within your class. This permission is applied when the security system calls . This property is write-once. ]]> @@ -340,9 +340,9 @@ method is called by the security system, not by application code. + The method is called by the security system, not by application code. - The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. + The security information described by is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses the information at run time. The system uses the returned by to convert the security information of the attribute target to a serializable form stored in metadata. ]]> diff --git a/xml/System.Net/WebProxy.xml b/xml/System.Net/WebProxy.xml index 97e2a15f46a..aff7f67c997 100644 --- a/xml/System.Net/WebProxy.xml +++ b/xml/System.Net/WebProxy.xml @@ -74,15 +74,15 @@ To obtain instances of the Web proxy class, you can use any of the following methods: -- The constructor. -- The method. -- The method. +- The constructor. +- The method. +- The method. - These methods each supply a instance that you can further customize; the difference between them is how the instance is initialized before it is returned to your application. The constructor returns an instance of the class with the property set to `null`. When a request uses a instance in this state, no proxy is used to send the request. + These methods each supply a instance that you can further customize; the difference between them is how the instance is initialized before it is returned to your application. The constructor returns an instance of the class with the property set to `null`. When a request uses a instance in this state, no proxy is used to send the request. - The method returns an instance of the class with the , , and properties set to the values used by the local computer. + The method returns an instance of the class with the , , and properties set to the values used by the local computer. - The method returns an instance of the class with it properties set according to a combination of Internet and configuration file settings. + The method returns an instance of the class with it properties set according to a combination of Internet and configuration file settings. The class supports automatic detection and execution of proxy configuration scripts. This feature is also known as Web Proxy Auto-Discovery (WPAD). When using automatic proxy configuration, a configuration script, typically named Wpad.dat, must be located, downloaded, compiled, and run. If these operations are successful, the script returns the proxies that can be used for a request. @@ -155,7 +155,7 @@ ## Remarks The parameterless constructor initializes an empty instance of the class with the property set to `null`. - When the property is `null`, the method returns `true` and the method returns the destination address. + When the property is `null`, the method returns `true` and the method returns the destination address. @@ -893,14 +893,14 @@ property contains the address of the proxy server. When automatic proxy detection is not enabled, and no automatic configuration script is specified, the property and determine the proxy used for a request. + The property contains the address of the proxy server. When automatic proxy detection is not enabled, and no automatic configuration script is specified, the property and determine the proxy used for a request. When the property is `null`, requests bypass the proxy and connect directly to the destination host. ## Examples - The following code example displays the properties of a object, including its . + The following code example displays the properties of a object, including its . :::code language="csharp" source="~/snippets/csharp/System.Net/WebProxy/Address/proxy.cs" id="Snippet1"::: @@ -957,7 +957,7 @@ is an array list of regular expression strings that describe the URIs that are accessed directly instead of through the proxy server. + The is an array list of regular expression strings that describe the URIs that are accessed directly instead of through the proxy server. ]]> @@ -1072,10 +1072,10 @@ ## Remarks The setting of the property determines whether to use the proxy server when accessing local Internet resources. - If is `true`, requests to local Internet resources do not use the proxy server. Local requests are identified by the lack of a period (.) in the URI, as in `http://webserver/`, or access the local server, including `http://localhost`, `http://loopback`, or `http://127.0.0.1`. When is `false`, all Internet requests are made through the proxy server. + If is `true`, requests to local Internet resources do not use the proxy server. Local requests are identified by the lack of a period (.) in the URI, as in `http://webserver/`, or access the local server, including `http://localhost`, `http://loopback`, or `http://127.0.0.1`. When is `false`, all Internet requests are made through the proxy server. > [!NOTE] -> Requests to a local host with a URI that contain a period use the proxy. To avoid using a proxy in these cases, create an entry for the host in the . +> Requests to a local host with a URI that contain a period use the proxy. To avoid using a proxy in these cases, create an entry for the host in the . @@ -1145,10 +1145,10 @@ property contains the authentication credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. In most client scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. + The property contains the authentication credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. In most client scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. > [!NOTE] -> If you set the property to credentials other than the , setting the property to `true` causes a . To prevent this, you must set the property to `null` before setting the property to `true`. Likewise, you cannot set this property to any value when is `true`. +> If you set the property to credentials other than the , setting the property to `true` causes a . To prevent this, you must set the property to `null` before setting the property to `true`. Likewise, you cannot set this property to any value when is `true`. ]]> @@ -1212,11 +1212,11 @@ method reads the nondynamic proxy settings from the computer's Internet options and creates a instance with those settings. + The method reads the nondynamic proxy settings from the computer's Internet options and creates a instance with those settings. - The method does not pick up any dynamic settings that are generated from scripts run by Internet Explorer, from automatic configuration entries, or from DHCP or DNS lookups. + The method does not pick up any dynamic settings that are generated from scripts run by Internet Explorer, from automatic configuration entries, or from DHCP or DNS lookups. - Applications should use the property instead of the method. + Applications should use the property instead of the method. > [!NOTE] > This property is not supported on .NET Core. @@ -1336,11 +1336,11 @@ method returns the URI that the instance uses to access the Internet resource. + The method returns the URI that the instance uses to access the Internet resource. - compares `destination` with the contents of , using the method. If returns `true`, returns `destination` and the instance does not use the proxy server. + compares `destination` with the contents of , using the method. If returns `true`, returns `destination` and the instance does not use the proxy server. - If `destination` is not in , the instance uses the proxy server and the property is returned. + If `destination` is not in , the instance uses the proxy server and the property is returned. @@ -1405,17 +1405,17 @@ method is used to determine whether to bypass the proxy server when accessing an Internet resource. + The method is used to determine whether to bypass the proxy server when accessing an Internet resource. - The and properties control the return value of the method. + The and properties control the return value of the method. - returns `true` under any of the following conditions: + returns `true` under any of the following conditions: -- If is `true` and `host` is a local URI. Local requests are identified by the lack of a period (.) in the URI, as in `http://webserver/`. +- If is `true` and `host` is a local URI. Local requests are identified by the lack of a period (.) in the URI, as in `http://webserver/`. -- If `host` matches a regular expression in . +- If `host` matches a regular expression in . -- If is `null`. +- If is `null`. All other conditions return `false`. @@ -1540,16 +1540,16 @@ ## Remarks Set this property to `true` when requests made by this object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - The following table shows the effect of setting the value, based on the value of the property. + The following table shows the effect of setting the value, based on the value of the property. -| value| value|Effect| +| value| value|Effect| |----------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| -||`true`|No effect.| -||`false`| is set to `null`.| -|`null`|`true`| is set to .| -|Any value other than or `null`|`true` or `false`|Setting throws an exception.| +||`true`|No effect.| +||`false`| is set to `null`.| +|`null`|`true`| is set to .| +|Any value other than or `null`|`true` or `false`|Setting throws an exception.| - If is `false`, you can change the property to any credentials. If is `true`, changing the property from (the value that is set when the property is set to `true`) will throw an exception. + If is `false`, you can change the property to any credentials. If is `true`, changing the property from (the value that is set when the property is set to `true`) will throw an exception. ]]> diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index aa7476abd46..76190eb245b 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -84,12 +84,12 @@ Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. + The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. - Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . > [!NOTE] -> Use the method to initialize new instances. Do not use the constructor. +> Use the method to initialize new instances. Do not use the constructor. > [!NOTE] > If the application that creates the WebRequest object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. @@ -170,10 +170,10 @@ ## Remarks - Use the method to initialize new instances. Do not use the constructor. + Use the method to initialize new instances. Do not use the constructor. ## Examples - The following example shows how to create a instance by calling the method on the class. + The following example shows how to create a instance by calling the method on the class. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/.ctor/source.vb" id="Snippet1"::: @@ -310,10 +310,10 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method cancels asynchronous requests to Internet resources started with the method. + The method cancels asynchronous requests to Internet resources started with the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ]]> @@ -450,15 +450,15 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. + The method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ## Examples - The following example uses the to asynchronously obtain the request stream. + The following example uses the to asynchronously obtain the request stream. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: @@ -531,18 +531,18 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. + The method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . > [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. +> If a WebException is thrown, use the and properties of the exception to determine the response from the server. ## Examples - The following example uses to asynchronously request the target resource. When the resource has been obtained, the specified callback method will be executed. + The following example uses to asynchronously request the target resource. When the resource has been obtained, the specified callback method will be executed. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: @@ -698,7 +698,7 @@ The property associates specific requests within an application to one or more connection pools. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ]]> @@ -763,7 +763,7 @@ The property contains the number of bytes of data sent to the Internet resource by the instance. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -842,7 +842,7 @@ The property contains the media type of the request. This is typically the MIME encoding of the content. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -926,9 +926,9 @@ ## Remarks - The method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. + The method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. - For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. + For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. The pre-registered reserve types already registered include the following: @@ -940,9 +940,9 @@ - `file://` - .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. + .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. - The method uses the `requestUriString` parameter to create a instance that it passes to the new . + The method uses the `requestUriString` parameter to create a instance that it passes to the new . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -950,7 +950,7 @@ ## Examples - The following example uses to instantiate an instance. A string representing the target URL is used as the constructor parameter. + The following example uses to instantiate an instance. A string representing the target URL is used as the constructor parameter. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webresponse_responseuri.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Create/webresponse_responseuri.vb" id="Snippet1"::: @@ -1026,13 +1026,13 @@ Note: In .NET for Win ## Remarks - The method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. + The method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. - For example, if you create a descendant, Handler1, to handle requests to `http://www.contoso.com/text/` and another named Handler2 to handle requests to `http://www.contoso.com/code/`, you can use method to return the WebRequest descendant associated with either specified URI. + For example, if you create a descendant, Handler1, to handle requests to `http://www.contoso.com/text/` and another named Handler2 to handle requests to `http://www.contoso.com/code/`, you can use method to return the WebRequest descendant associated with either specified URI. - To return a descendant of the class based on only the scheme portion of a URI, use the method. + To return a descendant of the class based on only the scheme portion of a URI, use the method. - For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. + For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. The pre-registered reserve types already registered include the following: @@ -1044,7 +1044,7 @@ Note: In .NET for Win - `file://` - .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. + .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1052,7 +1052,7 @@ Note: In .NET for Win ## Examples - The following example uses to instantiate an instance. A Uri representing the target URL is used as the constructor parameter. + The following example uses to instantiate an instance. A Uri representing the target URL is used as the constructor parameter. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webrequest_create.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Create/webrequest_create.vb" id="Snippet1"::: @@ -1122,9 +1122,9 @@ Note: In .NET for Win ## Remarks - The method returns a descendant instance based on only the scheme portion of a URI. + The method returns a descendant instance based on only the scheme portion of a URI. - For example, when a URI beginning with `http://` is passed in `requestUri`, an is returned by . If a URI beginning with `file://` is passed instead, the method will return a . + For example, when a URI beginning with `http://` is passed in `requestUri`, an is returned by . If a URI beginning with `file://` is passed instead, the method will return a . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET](/dotnet/framework/network-programming/network-tracing). @@ -1203,13 +1203,13 @@ Note: In .NET for Win ## Remarks - The method returns an instance of the class for the `requestUriString`. + The method returns an instance of the class for the `requestUriString`. - When a URI that begins with `http://` or `https://` is passed in the `requestUriString` parameter, a is returned by . Any other scheme will throw a . + When a URI that begins with `http://` or `https://` is passed in the `requestUriString` parameter, a is returned by . Any other scheme will throw a . - The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. + The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. - .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. + .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. ]]> @@ -1276,13 +1276,13 @@ Note: In .NET for Win ## Remarks - The method returns an instance of the class for the `requestUri`. + The method returns an instance of the class for the `requestUri`. - When a URI that begins with `http://` or `http://` is passed in the `requestUri` parameter, an is returned by . Another other scheme will throw a . + When a URI that begins with `http://` or `http://` is passed in the `requestUri` parameter, an is returned by . Another other scheme will throw a . - The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. + The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. - .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. + .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. ]]> @@ -1335,7 +1335,7 @@ Note: In .NET for Win ## Remarks -This property allows an application to determine which derived factory object was used to create the request. This object may be [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) or [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)), but it may also be a custom instance derived from . This allows an application to determine whether the browser hosting Silverlight, the Silverlight client, or some custom object handles HTTP requests and responses for the instance. The method allows an application to configure which derived type will be instantiated when making a request to a specific URI. creators are typically registered to handle a specific protocol, such HTTP or HTTPS, but can be registered to handle a request to a specific server or path on a server. This is useful when more than one derived type can process requests for the same protocol. The Microsoft Silverlight 3 and later runtime supports multiple HTTP handlers each having different capabilities. For example, a web service that uses Representational State Transfer (REST) might require the [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)) handler while a SOAP web service might be able to use the default [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) handler. +This property allows an application to determine which derived factory object was used to create the request. This object may be [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) or [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)), but it may also be a custom instance derived from . This allows an application to determine whether the browser hosting Silverlight, the Silverlight client, or some custom object handles HTTP requests and responses for the instance. The method allows an application to configure which derived type will be instantiated when making a request to a specific URI. creators are typically registered to handle a specific protocol, such HTTP or HTTPS, but can be registered to handle a request to a specific server or path on a server. This is useful when more than one derived type can process requests for the same protocol. The Microsoft Silverlight 3 and later runtime supports multiple HTTP handlers each having different capabilities. For example, a web service that uses Representational State Transfer (REST) might require the [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)) handler while a SOAP web service might be able to use the default [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) handler. ]]> @@ -1401,7 +1401,7 @@ This property allows an application to determine which property contains the authentication credentials required to access the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1560,7 +1560,7 @@ This property allows an application to determine which property reads proxy settings from the app.config file. If there is no config file, the current user's Internet options proxy settings are used. - If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. + If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. ]]> @@ -1624,18 +1624,18 @@ This property allows an application to determine which method completes an asynchronous stream request that was started by the method. + The method completes an asynchronous stream request that was started by the method. > [!NOTE] -> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . +> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ## Examples - The following example obtains and uses the request stream by calling the . The method completes the asynchronous call to . + The following example obtains and uses the request stream by calling the . The method completes the asynchronous call to . :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: @@ -1705,15 +1705,15 @@ This property allows an application to determine which method completes an asynchronous request for an Internet resource that was started with the method. + The method completes an asynchronous request for an Internet resource that was started with the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ## Examples - The following example calls the to retrieve the target resource. + The following example calls the to retrieve the target resource. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Abort/begingetresponse.cs" id="Snippet1"::: @@ -1837,17 +1837,17 @@ This property allows an application to determine which method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource. + The method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource. - The method provides synchronous access to the . For asynchronous access, use the and methods. + The method provides synchronous access to the . For asynchronous access, use the and methods. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ## Examples - The following example uses the method to obtain a stream and then writes data that stream. + The following example uses the method to obtain a stream and then writes data that stream. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: @@ -1908,9 +1908,9 @@ This property allows an application to determine which object will complete when the for writing data to the Internet resource is available. + This operation will not block. The returned object will complete when the for writing data to the Internet resource is available. - After you call , make sure you close the request stream before you call . + After you call , make sure you close the request stream before you call . This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -1968,15 +1968,15 @@ This property allows an application to determine which method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response. + The method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response. - The method provides synchronous access to the . For asynchronous access, use the and methods. + The method provides synchronous access to the . For asynchronous access, use the and methods. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . > [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. +> If a WebException is thrown, use the and properties of the exception to determine the response from the server. @@ -2042,7 +2042,7 @@ This property allows an application to determine which object will complete after a response to an Internet request is available. + This operation will not block. The returned object will complete after a response to an Internet request is available. This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -2099,9 +2099,9 @@ This property allows an application to determine which method reads the current user's Internet options proxy settings. This process includes the options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings. + method reads the current user's Internet options proxy settings. This process includes the options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings. - If your application impersonates several users, you can use the method to retrieve a proxy for each impersonated user. + If your application impersonates several users, you can use the method to retrieve a proxy for each impersonated user. ]]> @@ -2163,7 +2163,7 @@ This property allows an application to determine which property contains a instance containing the header information to send to the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2300,7 +2300,7 @@ This property allows an application to determine which property contains the request method to use in this request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2369,10 +2369,10 @@ This property allows an application to determine which property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. + With the exception of the first request, the property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ]]> @@ -2440,7 +2440,7 @@ This property allows an application to determine which property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2558,7 +2558,7 @@ This property allows an application to determine which method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. + The method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. The pre-registered reserve types already registered include the following: @@ -2570,9 +2570,9 @@ This property allows an application to determine which and methods. + For more information, see the and methods. - Duplicate prefixes are not allowed. returns `false` if an attempt is made to register a duplicate prefix. + Duplicate prefixes are not allowed. returns `false` if an attempt is made to register a duplicate prefix. > [!NOTE] > The class is registered to service requests for HTTP and HTTPS schemes by default. Attempts to register a different descendant for these schemes will fail. @@ -2640,10 +2640,10 @@ This property allows an application to determine which property contains the instance that method uses to create the request. + When overridden in a descendant class, the property contains the instance that method uses to create the request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2777,10 +2777,10 @@ This property allows an application to determine which property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. + The property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . diff --git a/xml/System.Net/WebResponse.xml b/xml/System.Net/WebResponse.xml index e365d4d331c..2508f300c6f 100644 --- a/xml/System.Net/WebResponse.xml +++ b/xml/System.Net/WebResponse.xml @@ -83,7 +83,7 @@ ## Remarks The class is the `abstract` base class from which protocol-specific response classes are derived. Applications can participate in request and response transactions in a protocol-agnostic manner using instances of the class while protocol-specific classes derived from carry out the details of the request. - Client applications do not create objects directly; they are created by calling the method on a instance. + Client applications do not create objects directly; they are created by calling the method on a instance. @@ -159,7 +159,7 @@ constructor directly; use the method on a instance. + Applications do not call the constructor directly; use the method on a instance. ]]> @@ -283,18 +283,18 @@ method cleans up the resources used by a and closes the underlying stream by calling the method. + The method cleans up the resources used by a and closes the underlying stream by calling the method. > [!NOTE] -> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . +> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . ## Examples - The following example uses the method to close the `WebResponse`. + The following example uses the method to close the `WebResponse`. :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/Close/webresponse_close.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebResponse/Close/webresponse_close.vb" id="Snippet1"::: @@ -356,10 +356,10 @@ property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. + The property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -429,7 +429,7 @@ The property contains the MIME content type of the response from the Internet resource, if known. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -676,15 +676,15 @@ method returns the data stream from the Internet resource. + The method returns the data stream from the Internet resource. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or +> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or ## Examples - The following example uses to return a instance. A small local buffer is used to read data from the and output it to the console. + The following example uses to return a instance. A small local buffer is used to read data from the and output it to the console. :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/GetResponseStream/webresponse_getresponsestream.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebResponse/GetResponseStream/webresponse_getresponsestream.vb" id="Snippet1"::: @@ -745,7 +745,7 @@ The property contains the name-value header pairs returned in the response. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -936,7 +936,7 @@ The property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . diff --git a/xml/System.Net/WebUtility.xml b/xml/System.Net/WebUtility.xml index ca8924ce704..f151b7e5c8a 100644 --- a/xml/System.Net/WebUtility.xml +++ b/xml/System.Net/WebUtility.xml @@ -417,7 +417,7 @@ ` are encoded into the escape sequences `%3C` and `%3E`. The method creates a URL-encoded string. + If characters such as blanks and punctuation are passed in an HTTP stream, they might be misinterpreted at the receiving end. URL encoding converts characters that are not allowed in a URL into equivalent hexadecimal escape sequences. The hexadecimal escape sequences are in uppercase. For example, the characters `<` and `>` are encoded into the escape sequences `%3C` and `%3E`. The method creates a URL-encoded string. URL decoding replaces hexadecimal escape sequences with corresponding ASCII character equivalents. For example, when embedded in a block of URL-encoded text, the escape sequences `%3c` and `%3e` are decoded into the characters `<` and `>`. @@ -481,7 +481,7 @@ method creates a URL-encoded byte array. + If characters such as blanks and punctuation are passed in an HTTP stream, they might be misinterpreted at the receiving end. URL encoding converts characters that are not allowed in a URL into equivalent hexadecimal escape sequences. The method creates a URL-encoded byte array. URL decoding replaces hexadecimal escape sequences with corresponding ASCII character equivalents. For example, when embedded in a block of URL-encoded text, the escape sequences `%3c` and `%3e` are decoded into the characters `<` and `>`. @@ -560,11 +560,11 @@ Each ' ' (space) character is converted to a `+` (plus) character. > [!NOTE] -> Replacing ' ' (space) with a '+' (plus) sign is expected only in query part of URI (by convention, not by standard) or in [`application/x-www-form-urlencoded`](https://url.spec.whatwg.org/#percent-encoded-bytes) HTTP content. Moreover, the above mentioned list of characters that are **not** replaced does not correspond neither to [URL specification](https://url.spec.whatwg.org) nor URI [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4). Use for RFC compliant transformation. +> Replacing ' ' (space) with a '+' (plus) sign is expected only in query part of URI (by convention, not by standard) or in [`application/x-www-form-urlencoded`](https://url.spec.whatwg.org/#percent-encoded-bytes) HTTP content. Moreover, the above mentioned list of characters that are **not** replaced does not correspond neither to [URL specification](https://url.spec.whatwg.org) nor URI [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4). Use for RFC compliant transformation. For example, when embedded in a block of text to be transmitted in a URL, the characters `<` and `>` are encoded as `%3c` and `%3e`. - The method reverses the encoding. + The method reverses the encoding. ]]> @@ -647,11 +647,11 @@ Each ' ' (space) character is converted to a `+` (plus) character. > [!NOTE] -> Replacing ' ' (space) with a '+' (plus) sign is expected only in query part of URI (by convention, not by standard) or in [`application/x-www-form-urlencoded`](https://url.spec.whatwg.org/#percent-encoded-bytes) HTTP content. Moreover, the above mentioned list of characters that are **not** replaced does not correspond neither to [URL specification](https://url.spec.whatwg.org) nor URI [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4). Use for RFC compliant transformation. +> Replacing ' ' (space) with a '+' (plus) sign is expected only in query part of URI (by convention, not by standard) or in [`application/x-www-form-urlencoded`](https://url.spec.whatwg.org/#percent-encoded-bytes) HTTP content. Moreover, the above mentioned list of characters that are **not** replaced does not correspond neither to [URL specification](https://url.spec.whatwg.org) nor URI [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4). Use for RFC compliant transformation. For example, when embedded in a block of text to be transmitted in a URL, the characters `<` and `>` are encoded as `%3c` and `%3e`. - The method reverses the encoding. + The method reverses the encoding. ]]>