Skip to content

Commit 5075761

Browse files
gewarrengewarren
authored
add ioexception (#8811)
1 parent b0cbc42 commit 5075761

File tree

1 file changed

+24
-26
lines changed

1 file changed

+24
-26
lines changed

‎xml/System.IO/FileStream.xml

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -4076,6 +4076,7 @@ If the write operation is successful, the position within the file stream advanc
40764076
40774077
]]></format>
40784078
</remarks>
4079+
<exception cref="T:System.IO.IOException">.NET 8 and later versions: The underlying pipe is closed or disconnected.</exception>
40794080
</Docs>
40804081
</Member>
40814082
<Member MemberName="Write">
@@ -4141,19 +4142,18 @@ If the write operation is successful, the position within the file stream advanc
41414142
<remarks>
41424143
<format type="text/markdown"><![CDATA[
41434144
4144-
## Remarks
4145-
This method overrides <xref:System.IO.Stream.Write%2A>.
4145+
## Remarks
4146+
4147+
This method overrides <xref:System.IO.Stream.Write%2A>.
41464148
4147-
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.
4149+
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.
41484150
41494151
> [!NOTE]
4150-
> Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite%2A>.
4152+
> Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite%2A>.
41514153
4152-
Do not interrupt a thread that is 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.
4154+
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.
41534155
4154-
For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
4155-
4156-
4156+
For a list of common file and directory operations, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
41574157
41584158
## Examples
41594159
This code example is part of a larger example provided for the <xref:System.IO.FileStream.Lock%2A> method.
@@ -4174,12 +4174,16 @@ If the write operation is successful, the position within the file stream advanc
41744174

41754175
-or-
41764176

4177-
Another thread may have caused an unexpected change in the position of the operating system's file handle.</exception>
4177+
Another thread may have caused an unexpected change in the position of the operating system's file handle.
4178+
4179+
-or-
4180+
4181+
.NET 8 and later versions: The underlying pipe is closed or disconnected.</exception>
41784182
<exception cref="T:System.ObjectDisposedException">The stream is closed.</exception>
41794183
<exception cref="T:System.NotSupportedException">The current stream instance does not support writing.</exception>
4180-
<related type="Article" href="/dotnet/standard/io/">File and Stream I/O</related>
4181-
<related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read Text from a File</related>
4182-
<related type="Article" href="/dotnet/standard/io/how-to-write-text-to-a-file">How to: Write Text to a File</related>
4184+
<related type="Article" href="/dotnet/standard/io/">File and stream I/O</related>
4185+
<related type="Article" href="/dotnet/standard/io/how-to-read-text-from-a-file">How to: Read text from a file</related>
4186+
<related type="Article" href="/dotnet/standard/io/how-to-write-text-to-a-file">How to: Write text to a file</related>
41834187
</Docs>
41844188
</Member>
41854189
<Member MemberName="WriteAsync">
@@ -4224,7 +4228,7 @@ If the write operation is successful, the position within the file stream advanc
42244228
42254229
## Remarks
42264230
4227-
The `WriteAsync` method lets you 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#.
4231+
The `WriteAsync` method lets you perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in apps where a time-consuming stream operation can block the UI thread and make your app appear as if it isn't working.
42284232
42294233
Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing.
42304234
@@ -4296,21 +4300,19 @@ If the operation is canceled before it completes, the returned task contains the
42964300
<format type="text/markdown"><![CDATA[
42974301
42984302
## Remarks
4299-
The <xref:System.IO.FileStream.WriteAsync%2A> method enables you to perform resource-intensive file operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#.
4303+
The <xref:System.IO.FileStream.WriteAsync%2A> 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.
43004304
43014305
Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing.
43024306
4303-
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property. If the handle to the file is disposed, the returned task contains the <xref:System.ObjectDisposedException> exception in the <xref:System.Threading.Tasks.Task.Exception%2A> property.
4304-
4305-
4307+
If the operation is canceled before it completes, the returned task contains the <xref:System.Threading.Tasks.TaskStatus.Canceled> value for the <xref:System.Threading.Tasks.Task.Status%2A> property. If the handle to the file is disposed, the returned task contains the <xref:System.ObjectDisposedException> exception in the <xref:System.Threading.Tasks.Task.Exception%2A> property.
4308+
4309+
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 <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)>.
43064310
43074311
## Examples
43084312
The following example shows how to write asynchronously to a file.
43094313
43104314
:::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example3.cs" id="Snippet3":::
4311-
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3":::
4312-
4313-
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 <xref:System.ArgumentException>, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <xref:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)>.
4315+
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3":::
43144316
43154317
]]></format>
43164318
</remarks>
@@ -4319,9 +4321,6 @@ If the operation is canceled before it completes, the returned task contains the
43194321
<exception cref="T:System.ArgumentOutOfRangeException">
43204322
<paramref name="offset" /> or <paramref name="count" /> is negative.</exception>
43214323
<exception cref="T:System.ArgumentException">The sum of <paramref name="offset" /> and <paramref name="count" /> is larger than the buffer length.</exception>
4322-
<exception cref="T:System.NotSupportedException">The stream does not support writing.</exception>
4323-
<exception cref="T:System.ObjectDisposedException">The stream has been disposed.</exception>
4324-
<exception cref="T:System.InvalidOperationException">The stream is currently in use by a previous write operation.</exception>
43254324
<related type="Article" href="/dotnet/standard/threading/cancellation-in-managed-threads">Cancellation</related>
43264325
</Docs>
43274326
</Member>
@@ -4383,9 +4382,7 @@ If the operation is canceled before it completes, the returned task contains the
43834382
Use `WriteByte` to write a byte to a `FileStream` efficiently. If the stream is closed or not writable, an exception will be thrown.
43844383
43854384
> [!NOTE]
4386-
> Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite%2A>.
4387-
4388-
4385+
> Use the <xref:System.IO.FileStream.CanWrite%2A> property to determine whether the current instance supports writing. For additional information, see <xref:System.IO.Stream.CanWrite%2A>.
43894386
43904387
## Examples
43914388
The following code example shows how to write data to a file, byte by byte, and then verify that the data was written correctly.
@@ -4398,6 +4395,7 @@ If the operation is canceled before it completes, the returned task contains the
43984395
</remarks>
43994396
<exception cref="T:System.ObjectDisposedException">The stream is closed.</exception>
44004397
<exception cref="T:System.NotSupportedException">The stream does not support writing.</exception>
4398+
<exception cref="T:System.IO.IOException">.NET 8 and later versions: The underlying pipe is closed or disconnected.</exception>
44014399
<block subset="none" type="overrides">
44024400
<para>The default implementation on <see langword="Stream" /> creates a new single-byte array and then calls <see cref="M:System.IO.Stream.Write(System.Byte[],System.Int32,System.Int32)" />. While this is formally correct, it is inefficient. Any stream with an internal buffer should override this method and provide a much more efficient version that reads the buffer directly, avoiding the extra array allocation on every call.
44034401

0 commit comments

Comments
 (0)