Stream 类

定义

提供字节序列的一般视图。 这是一个抽象类。

public ref class Stream abstract : IDisposable
public ref class Stream abstract : MarshalByRefObject, IAsyncDisposable, IDisposable
public ref class Stream abstract : MarshalByRefObject, IDisposable
public abstract class Stream : IDisposable
public abstract class Stream : MarshalByRefObject, IAsyncDisposable, IDisposable
public abstract class Stream : MarshalByRefObject, IDisposable
[System.Serializable]
public abstract class Stream : MarshalByRefObject, IDisposable
[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public abstract class Stream : MarshalByRefObject, IDisposable
type Stream = class
    interface IDisposable
type Stream = class
    inherit MarshalByRefObject
    interface IAsyncDisposable
    interface IDisposable
type Stream = class
    inherit MarshalByRefObject
    interface IDisposable
[<System.Serializable>]
type Stream = class
    inherit MarshalByRefObject
    interface IDisposable
[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type Stream = class
    inherit MarshalByRefObject
    interface IDisposable
Public MustInherit Class Stream
Implements IDisposable
Public MustInherit Class Stream
Inherits MarshalByRefObject
Implements IAsyncDisposable, IDisposable
Public MustInherit Class Stream
Inherits MarshalByRefObject
Implements IDisposable
继承
Stream
继承
派生
属性
实现

示例

以下示例演示如何使用两个 FileStream 对象以异步方式将文件从一个目录复制到另一个目录。 FileStream 类是从 Stream 类派生的。 需要注意 Click 控件的 Button 事件处理程序具有 async 修饰符标记,因为它调用异步方法。

using System;
using System.Threading.Tasks;
using System.Windows;
using System.IO;

namespace WpfApplication
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }

        private async void Button_Click(object sender, RoutedEventArgs e)
        {
            string StartDirectory = @"c:\Users\exampleuser\start";
            string EndDirectory = @"c:\Users\exampleuser\end";

            foreach (string filename in Directory.EnumerateFiles(StartDirectory))
            {
                using (FileStream SourceStream = File.Open(filename, FileMode.Open))
                {
                    using (FileStream DestinationStream = File.Create(EndDirectory + filename.Substring(filename.LastIndexOf('\\'))))
                    {
                        await SourceStream.CopyToAsync(DestinationStream);
                    }
                }
            }
        }
    }
}
Imports System.IO

Class MainWindow

    Private Async Sub Button_Click(sender As Object, e As RoutedEventArgs)
        Dim StartDirectory As String = "c:\Users\exampleuser\start"
        Dim EndDirectory As String = "c:\Users\exampleuser\end"

        For Each filename As String In Directory.EnumerateFiles(StartDirectory)
            Using SourceStream As FileStream = File.Open(filename, FileMode.Open)
                Using DestinationStream As FileStream = File.Create(EndDirectory + filename.Substring(filename.LastIndexOf("\"c)))
                    Await SourceStream.CopyToAsync(DestinationStream)
                End Using

            End Using
        Next
    End Sub

End Class

注解

Stream 是所有流的抽象基类。 流是字节序列的抽象,例如文件、输入/输出设备、进程中通信管道或 TCP/IP 套接字。 类 Stream 及其派生类提供这些不同类型的输入和输出的通用视图,并将程序员与操作系统和基础设备的特定详细信息隔离开来。

流涉及三个基本操作:

  • 可以从流中读取数据。 读取是将数据从流传输到数据结构中,例如字节数组。

  • 可以写入流。 写入是将数据从数据结构传输到流中。

  • 流可以支持查找。 查找是指查询和修改流中的当前位置。 搜寻功能取决于流具有的后备存储类型。 例如,网络流没有当前位置的统一概念,因此通常不支持查找。

继承自 Stream 的一些更常用的流包括 FileStream、 和 MemoryStream

根据基础数据源或存储库,流可能仅支持其中某些功能。 可以使用 类的 、 CanWriteCanSeek 属性Stream查询流的功能CanRead

ReadWrite 方法以各种格式读取和写入数据。 对于支持查找的流,请使用 SeekSetLength 方法以及 PositionLength 属性来查询和修改流的当前位置和长度。

此类型实现 IDisposable 接口。 在使用完类型后,您应直接或间接释放类型。 若要直接释放类型,请在 try/catch 块中调用其 Dispose 方法。 若要间接释放类型,请使用 using(在 C# 中)或 Using(在 Visual Basic 中)等语言构造。 有关详细信息,请参阅 IDisposable 接口主题中的“使用实现 IDisposable 的对象”一节。

释放 Stream 对象会刷新所有缓冲的数据,并实质上为你调用 Flush 方法。 Dispose 还会释放操作系统资源,例如文件句柄、网络连接或用于任何内部缓冲的内存。 类 BufferedStream 提供将缓冲流包装在另一个流周围的功能,以提高读取和写入性能。

从 .NET Framework 4.5 开始, Stream 类包括用于简化异步操作的异步方法。 异步方法 Async 的名称中包含 ,例如 ReadAsyncWriteAsyncCopyToAsyncFlushAsync。 这些方法使你能够执行资源密集型 I/O 操作,而不会阻止main线程。 在 Windows 8.x 应用商店应用或桌面应用中一个耗时的流操作可能阻塞 UI 线程并让应用看起来好像不工作时,这种性能的考虑就显得尤为重要了。 异步方法与 async Visual Basic 和 C# 中的 和 await 关键字结合使用。

在 Windows 8.x 应用商店应用中使用时, Stream 包括两个扩展方法: AsInputStreamAsOutputStream。 这些方法将 Stream 对象转换为Windows 运行时中的流。 还可以使用 AsStreamForReadAsStreamForWrite 方法将 Windows 运行时 Stream 中的流转换为 对象。 有关详细信息,请参阅如何:在.NET Framework流和Windows 运行时流之间转换

某些流实现对基础数据执行本地缓冲以提高性能。 对于此类流,可以使用 FlushFlushAsync 方法来清除任何内部缓冲区,并确保所有数据都已写入基础数据源或存储库。

如果需要没有后备存储 (也称为位存储桶) 的流,请使用 Null 字段检索专为此目的设计的流的实例。

实施者说明

实现 的Stream派生类时,必须为 和 Write(Byte[], Int32, Int32) 方法提供实现Read(Byte[], Int32, Int32)。 异步方法 ReadAsync(Byte[], Int32, Int32)WriteAsync(Byte[], Int32, Int32)CopyToAsync(Stream) 在其实现中使用同步方法 Read(Byte[], Int32, Int32)Write(Byte[], Int32, Int32) 。 因此,和 Write(Byte[], Int32, Int32)Read(Byte[], Int32, Int32)实现将正确使用异步方法。 和 的默认实现ReadByte()创建一个新的单元素字节数组,然后调用 和 Write(Byte[], Int32, Int32)Read(Byte[], Int32, Int32)实现。WriteByte(Byte)Stream派生时,建议重写这些方法来访问内部缓冲区(如果有),以便大幅提高性能。 还必须提供 、、、 Flush()Seek(Int64, SeekOrigin)CanSeekCanWriteLengthPositionSetLength(Int64)CanRead实现。

不要重写 Close() 方法,而是将所有 Stream 清理逻辑放在 方法中 Dispose(Boolean) 。 有关详细信息,请参阅 实现 Dispose 方法

构造函数

Stream()

初始化 Stream 类的新实例。

字段

Null

无后备存储区的 Stream

属性

CanRead

当在派生类中重写时,获取指示当前流是否支持读取的值。

CanSeek

当在派生类中重写时,获取指示当前流是否支持查找功能的值。

CanTimeout

获取一个值,该值确定当前流是否可以超时。

CanWrite

当在派生类中重写时,获取指示当前流是否支持写入功能的值。

Length

当在派生类中重写时,获取流长度(以字节为单位)。

Position

当在派生类中重写时,获取或设置当前流中的位置。

ReadTimeout

获取或设置一个值(以毫秒为单位),该值确定流在超时前将尝试读取的时间。

WriteTimeout

获取或设置一个值(以毫秒为单位),该值确定流在超时前将尝试写入多长时间。

方法

BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)

开始异步读操作。 (请考虑改用 ReadAsync(Byte[], Int32, Int32)。)

BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)

开始异步写操作。 (请考虑改用 WriteAsync(Byte[], Int32, Int32)。)

Close()

关闭当前流并释放与之关联的所有资源(如套接字和文件句柄)。 不直接调用此方法,而应确保流得以正确释放。

CopyTo(Stream)

从当前流中读取字节并将其写入到另一流中。 这两个流位置都以复制的字节数为高级。

CopyTo(Stream, Int32)

使用指定的缓冲区大小,从当前流中读取字节并将其写入到另一流中。 这两个流位置都以复制的字节数为高级。

CopyToAsync(Stream)

从当前流中异步读取字节并将其写入到另一个流中。 这两个流位置都以复制的字节数为高级。

CopyToAsync(Stream, CancellationToken)

通过指定的取消令牌,从当前流中异步读取字节并将其写入到另一个流中。 这两个流位置都以复制的字节数为高级。

CopyToAsync(Stream, Int32)

使用指定的缓冲区大小,从当前流中异步读取字节并将其写入到另一流中。 这两个流位置都以复制的字节数为高级。

CopyToAsync(Stream, Int32, CancellationToken)

使用指定的缓冲区大小和取消令牌,从当前流中异步读取字节并将其写入到另一个流中。 这两个流位置都以复制的字节数为高级。

CreateObjRef(Type)

创建一个对象,该对象包含生成用于与远程对象进行通信的代理所需的全部相关信息。

(继承自 MarshalByRefObject)
CreateWaitHandle()
已过时.
已过时.
已过时.

分配 WaitHandle 对象。

Dispose()

释放由 Stream 使用的所有资源。

Dispose(Boolean)

释放由 Stream 占用的非托管资源,还可以另外再释放托管资源。

DisposeAsync()

异步释放 Stream 使用的非托管资源。

EndRead(IAsyncResult)

等待挂起的异步读取完成。 (请考虑改用 ReadAsync(Byte[], Int32, Int32)。)

EndWrite(IAsyncResult)

结束异步写操作。 (请考虑改用 WriteAsync(Byte[], Int32, Int32)。)

Equals(Object)

确定指定对象是否等于当前对象。

(继承自 Object)
Flush()

当在派生类中重写时,将清除该流的所有缓冲区,并使得所有缓冲数据被写入到基础设备。

FlushAsync()

异步清除此流的所有缓冲区并导致所有缓冲数据都写入基础设备中。

FlushAsync(CancellationToken)

异步清理此流的所有缓冲区,导致所有缓冲数据都写入基础设备,并且监控取消请求。

GetHashCode()

作为默认哈希函数。

(继承自 Object)
GetLifetimeService()
已过时.

检索控制此实例的生存期策略的当前生存期服务对象。

(继承自 MarshalByRefObject)
GetType()

获取当前实例的 Type

(继承自 Object)
InitializeLifetimeService()
已过时.

获取生存期服务对象来控制此实例的生存期策略。

(继承自 MarshalByRefObject)
MemberwiseClone()

创建当前 Object 的浅表副本。

(继承自 Object)
MemberwiseClone(Boolean)

创建当前 MarshalByRefObject 对象的浅表副本。

(继承自 MarshalByRefObject)
ObjectInvariant()
已过时.

提供对 Contract 的支持。

Read(Byte[], Int32, Int32)

当在派生类中重写时,从当前流读取字节序列,并将此流中的位置提升读取的字节数。

Read(Span<Byte>)

当在派生类中重写时,从当前流读取字节序列,并将此流中的位置提升读取的字节数。

ReadAsync(Byte[], Int32, Int32)

从当前流异步读取字节序列,并将流中的位置提升读取的字节数。

ReadAsync(Byte[], Int32, Int32, CancellationToken)

从当前流异步读取字节的序列,将流中的位置提升读取的字节数,并监视取消请求。

ReadAsync(Memory<Byte>, CancellationToken)

从当前流异步读取字节的序列,将流中的位置提升读取的字节数,并监视取消请求。

ReadAtLeast(Span<Byte>, Int32, Boolean)

从当前流中至少读取最小字节数,并按读取的字节数提升流中的位置。

ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)

从当前流异步读取至少最小字节数,将流中的位置按读取的字节数前进,并监视取消请求。

ReadByte()

从流中读取一个字节,并将流内的位置向前提升一个字节,或者如果已到达流结尾,则返回 -1。

ReadExactly(Byte[], Int32, Int32)

count从当前流中读取字节数,并提升流中的位置。

ReadExactly(Span<Byte>)

从当前流中读取字节,并推进流中的位置, buffer 直到 填充 。

ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)

从当前流异步读取 count 字节数,推进流中的位置,并监视取消请求。

ReadExactlyAsync(Memory<Byte>, CancellationToken)

从当前流异步读取字节,推进流中的位置,直到 buffer 填充,并监视取消请求。

Seek(Int64, SeekOrigin)

当在派生类中重写时,设置当前流中的位置。

SetLength(Int64)

当在派生类中重写时,设置当前流的长度。

Synchronized(Stream)

在指定的 Stream 对象周围创建线程安全(同步)包装。

ToString()

返回表示当前对象的字符串。

(继承自 Object)
ValidateBufferArguments(Byte[], Int32, Int32)

验证提供给在 上 Stream读取和写入方法的参数。

ValidateCopyToArguments(Stream, Int32)

验证提供给 CopyTo(Stream, Int32)CopyToAsync(Stream, Int32, CancellationToken) 方法的参数。

Write(Byte[], Int32, Int32)

当在派生类中重写时,向当前流中写入字节序列,并将此流中的当前位置提升写入的字节数。

Write(ReadOnlySpan<Byte>)

当在派生类中重写时,向当前流中写入字节序列,并将此流中的当前位置提升写入的字节数。

WriteAsync(Byte[], Int32, Int32)

将字节序列异步写入当前流,并将流的当前位置提升写入的字节数。

WriteAsync(Byte[], Int32, Int32, CancellationToken)

将字节的序列异步写入当前流,将该流中的当前位置向前移动写入的字节数,并监视取消请求。

WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)

将字节的序列异步写入当前流,将该流中的当前位置向前移动写入的字节数,并监视取消请求。

WriteByte(Byte)

将一个字节写入流内的当前位置,并将流内的位置向前提升一个字节。

显式接口实现

IDisposable.Dispose()

释放由 Stream 使用的所有资源。

扩展方法

AsInputStream(Stream)

将适用于 Windows 应用商店应用的 .NET 中的托管流转换为 Windows 运行时中的输入流。

AsOutputStream(Stream)

将适用于 Windows 应用商店应用的 .NET 中的托管流转换为 Windows 运行时中的输出流。

AsRandomAccessStream(Stream)

将指定的流转换为随机访问流。

ConfigureAwait(IAsyncDisposable, Boolean)

配置如何执行从异步可处置项返回的任务的等待。

适用于

另请参阅