FileStream Classe

Definição

Namespace:

System.IO

Assemblies:

netstandard.dll, System.Runtime.dll

Origem:

FileStream.cs

Fornece um Stream arquivo para dar suporte a operações de leitura e gravação síncronas e assíncronas.

public ref class FileStream : System::IO::Stream

public class FileStream : System.IO.Stream

type FileStream = class
    inherit Stream

Public Class FileStream
Inherits Stream

Herança

Object

MarshalByRefObject

Stream

FileStream

Derivado

System.IO.IsolatedStorage.IsolatedStorageFileStream

Exemplos

O exemplo a seguir demonstra alguns dos FileStream construtores.

using System;
using System.IO;
using System.Text;

class Test
{

    public static void Main()
    {
        string path = @"c:\temp\MyTest.txt";

        // Delete the file if it exists.
        if (File.Exists(path))
        {
            File.Delete(path);
        }

        //Create the file.
        using (FileStream fs = File.Create(path))
        {
            AddText(fs, "This is some text");
            AddText(fs, "This is some more text,");
            AddText(fs, "\r\nand this is on a new line");
            AddText(fs, "\r\n\r\nThe following is a subset of characters:\r\n");

            for (int i=1;i < 120;i++)
            {
                AddText(fs, Convert.ToChar(i).ToString());
            }
        }

        //Open the stream and read it back.
        using (FileStream fs = File.OpenRead(path))
        {
            byte[] b = new byte[1024];
            UTF8Encoding temp = new UTF8Encoding(true);
            int readLen;
            while ((readLen = fs.Read(b,0,b.Length)) > 0)
            {
                Console.WriteLine(temp.GetString(b,0,readLen));
            }
        }
    }

    private static void AddText(FileStream fs, string value)
    {
        byte[] info = new UTF8Encoding(true).GetBytes(value);
        fs.Write(info, 0, info.Length);
    }
}

open System
open System.IO
open System.Text

let addText (fs:FileStream) (value: string) =
    let info = UTF8Encoding(true).GetBytes value
    fs.Write(info, 0, info.Length);

let path = @"c:\temp\MyTest.txt"

// Delete the file if it exists.
if File.Exists path then
    File.Delete path

//Create the file.
do
    use fs = File.Create path

    addText fs "This is some text"
    addText fs "This is some more text,"
    addText fs "\r\nand this is on a new line"
    addText fs "\r\n\r\nThe following is a subset of characters:\r\n"

    for i = 1 to 119 do
        Convert.ToChar i
        |> string
        |> addText fs
    
do
    //Open the stream and read it back.
    use fs = File.OpenRead path
    let b = Array.zeroCreate 1024
    let temp = UTF8Encoding true
    let mutable readLen = fs.Read(b,0,b.Length);
    while readLen> 0 do
        printfn $"{temp.GetString(b,0,readLen)}"
        readLen <- fs.Read(b,0,b.Length)

Imports System.IO
Imports System.Text

Public Class Test

    Public Shared Sub Main()
        Dim path As String = "c:\temp\MyTest.txt"

        ' Delete the file if it exists.
        If File.Exists(path) Then
            File.Delete(path)
        End If

        'Create the file.
        Dim fs As FileStream = File.Create(path)

        AddText(fs, "This is some text")
        AddText(fs, "This is some more text,")
        AddText(fs, Environment.NewLine & "and this is on a new line")
        AddText(fs, Environment.NewLine & Environment.NewLine)
        AddText(fs, "The following is a subset of characters:" & Environment.NewLine)

        Dim i As Integer

        For i = 1 To 120
            AddText(fs, Convert.ToChar(i).ToString())

        Next

        fs.Close()

        'Open the stream and read it back.
        fs = File.OpenRead(path)
        Dim b(1023) As Byte
        Dim temp As UTF8Encoding = New UTF8Encoding(True)

        Do While fs.Read(b, 0, b.Length) > 0
            Console.WriteLine(temp.GetString(b))
        Loop

        fs.Close()
    End Sub

    Private Shared Sub AddText(ByVal fs As FileStream, ByVal value As String)
        Dim info As Byte() = New UTF8Encoding(True).GetBytes(value)
        fs.Write(info, 0, info.Length)
    End Sub
End Class

O exemplo a seguir mostra como gravar em um arquivo de forma assíncrona. Esse código é executado em um aplicativo WPF que tem um TextBlock chamado UserInput e um botão conectado a um manipulador de eventos Click chamado Button_Click. O caminho do arquivo precisa ser alterado para um arquivo que existe no computador.

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

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

        private async void Button_Click(object sender, RoutedEventArgs e)
        {
            UnicodeEncoding uniencoding = new UnicodeEncoding();
            string filename = @"c:\Users\exampleuser\Documents\userinputlog.txt";

            byte[] result = uniencoding.GetBytes(UserInput.Text);

            using (FileStream SourceStream = File.Open(filename, FileMode.OpenOrCreate))
            {
                SourceStream.Seek(0, SeekOrigin.End);
                await SourceStream.WriteAsync(result, 0, result.Length);
            }
        }
    }
}

Imports System.IO
Imports System.Text

Class MainWindow
    Private Async Sub Button_Click(sender As Object, e As RoutedEventArgs)
        Dim uniencoding As UnicodeEncoding = New UnicodeEncoding()
        Dim filename As String = "c:\Users\exampleuser\Documents\userinputlog.txt"

        Dim result As Byte() = uniencoding.GetBytes(UserInput.Text)

        Using SourceStream As FileStream = File.Open(filename, FileMode.OpenOrCreate)
            SourceStream.Seek(0, SeekOrigin.End)
            Await SourceStream.WriteAsync(result, 0, result.Length)
        End Using
    End Sub
End Class

Comentários

Use a FileStream classe para ler, gravar, abrir e fechar arquivos em um sistema de arquivos e manipular outros identificadores do sistema operacional relacionados a arquivos, incluindo pipes, entrada padrão e saída padrão. Você pode usar os Readmétodos, , WriteCopyToe Flush para executar operações síncronas ou , ReadAsyncWriteAsynce CopyToAsyncFlushAsync métodos para executar operações assíncronas. Use os métodos assíncronos para executar operações de arquivo com uso intensivo de recursos sem bloquear o thread principal. Essa consideração de desempenho é particularmente importante em um aplicativo de área de trabalho em que uma operação de fluxo demorada pode bloquear o thread da interface do usuário e fazer seu aplicativo aparecer como se não estivesse funcionando. FileStream armazena dados de entrada e saída para melhor desempenho.

Importante

Esse tipo implementa a IDisposable interface. Quando terminar de usar esse tipo ou objeto, você deverá descartá-lo de forma direta ou indireta. Para descartar o tipo diretamente, chame o método Dispose dele em um bloco try/catch. Para descartá-lo indiretamente, use um constructo de linguagem como using (em C#) ou Using (no Visual Basic). Para obter mais informações, consulte a seção "Usando um objeto que implementa idisposable" no tópico da IDisposable interface.

A propriedade IsAsync detecta se o identificador de arquivo foi aberto assíncronamente. Especifique esse valor ao criar uma instância da classe FileStream usando um construtor que tenha como parâmetro um isAsync, useAsync, ou options. Quando a propriedade é true, o fluxo utiliza E/S sobreposta para executar operações de arquivo de forma assíncrona. No entanto, a propriedade IsAsync não precisa ser true para chamar o método ReadAsync, WriteAsync ou o método CopyToAsync. Quando a propriedade IsAsync é false e você chama as operações de leitura e gravação assíncronas, o thread da interface do usuário ainda não é bloqueado, mas a operação de E/S real é executada de forma síncrona.

O Seek método dá suporte ao acesso aleatório a arquivos. Seek permite que a posição de leitura/gravação seja movida para qualquer posição dentro do arquivo. Isso é feito com parâmetros de ponto de referência de offset de bytes. O deslocamento de bytes é relativo ao ponto de referência de busca, que pode ser o início, a posição atual ou o fim do arquivo subjacente, conforme representado pelos três membros da enumeração SeekOrigin.

Note

Os arquivos de disco sempre dão suporte a acesso aleatório. No momento da construção, o valor da propriedade CanSeek é definido como true ou false dependendo do tipo de arquivo subjacente. Se o tipo de arquivo subjacente for FILE_TYPE_DISK, conforme definido em winbase.h, o valor da propriedade CanSeek é true. Caso contrário, o valor da CanSeek propriedade será false.

Se um processo terminar com parte de um arquivo bloqueado ou fechar um arquivo com bloqueios pendentes, o comportamento será indefinido.

Para operações de diretório e outras operações de arquivo, consulte as classes File, Directory e Path. A File classe é uma classe de utilitário que tem métodos estáticos principalmente para a criação de objetos com base em caminhos de FileStream arquivo. A MemoryStream classe cria um fluxo de uma matriz de bytes e é semelhante à FileStream classe.

Para obter uma lista de operações comuns de arquivo e diretório, consulte Tarefas comuns de E/S.

Detecção de alterações de posição do fluxo

Quando um objeto FileStream não tem uma retenção exclusiva em seu identificador, outro thread pode acessar o identificador de arquivo simultaneamente e alterar a posição do ponteiro de arquivo do sistema operacional associado ao identificador de arquivo. Nesse caso, a posição armazenada em cache no FileStream objeto e os dados armazenados em cache no buffer podem ser comprometidos. O objeto FileStream realiza verificações de rotina nos métodos que acessam o buffer armazenado em cache para garantir que a posição do identificador do sistema operacional seja a mesma que a posição armazenada em cache usada pelo objeto FileStream.

Se uma alteração inesperada na posição do identificador for detectada em uma chamada para o método Read, o .NET descartará o conteúdo do buffer e lerá o fluxo do arquivo novamente. Isso pode afetar o desempenho, dependendo do tamanho do arquivo e de qualquer outro processo que possa afetar a posição do fluxo de arquivos.

Se uma alteração inesperada na posição do identificador for detectada em uma chamada ao método Write, o conteúdo do buffer será descartado e uma exceção IOException será gerada.

Um FileStream objeto não terá uma retenção exclusiva em seu identificador quando a SafeFileHandle propriedade for acessada para expor o identificador ou o FileStream objeto receber a SafeFileHandle propriedade em seu construtor.

Construtores

Nome	Description
FileStream(IntPtr, FileAccess, Boolean, Int32, Boolean)	Obsoleto. Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada, FileStream a propriedade da instância, o tamanho do buffer e o estado síncrono ou assíncrono.
FileStream(IntPtr, FileAccess, Boolean, Int32)	Obsoleto. Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação, FileStream a propriedade da instância e o tamanho do buffer especificados.
FileStream(IntPtr, FileAccess, Boolean)	Obsoleto. Inicializa uma nova instância da classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada e FileStream a propriedade da FileStream instância.
FileStream(IntPtr, FileAccess)	Obsoleto. Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada.
FileStream(SafeFileHandle, FileAccess, Int32, Boolean)	Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada, o tamanho do buffer e o estado síncrono ou assíncrono.
FileStream(SafeFileHandle, FileAccess, Int32)	Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada e o tamanho do buffer.
FileStream(SafeFileHandle, FileAccess)	Inicializa uma nova instância da FileStream classe para o identificador de arquivo especificado, com a permissão de leitura/gravação especificada.
FileStream(String, FileMode, FileAccess, FileShare, Int32, Boolean)	Inicializa uma nova instância da FileStream classe com o caminho especificado, o modo de criação, a permissão de leitura/gravação e compartilhamento, o tamanho do buffer e o estado síncrono ou assíncrono.
FileStream(String, FileMode, FileAccess, FileShare, Int32, FileOptions)	Inicializa uma nova instância da FileStream classe com o caminho especificado, o modo de criação, a permissão de leitura/gravação e compartilhamento, o acesso que outros FileStreams podem ter para o mesmo arquivo, o tamanho do buffer e opções de arquivo adicionais.
FileStream(String, FileMode, FileAccess, FileShare, Int32)	Inicializa uma nova instância da FileStream classe com o caminho, o modo de criação, a permissão de leitura/gravação e compartilhamento especificados e o tamanho do buffer.
FileStream(String, FileMode, FileAccess, FileShare)	Inicializa uma nova instância da FileStream classe com o caminho, o modo de criação, a permissão de leitura/gravação e a permissão de compartilhamento especificados.
FileStream(String, FileMode, FileAccess)	Inicializa uma nova instância da FileStream classe com o caminho, o modo de criação e a permissão de leitura/gravação especificados.
FileStream(String, FileMode)	Inicializa uma nova instância da FileStream classe com o caminho e o modo de criação especificados.
FileStream(String, FileStreamOptions)	Inicializa uma nova instância da FileStream classe com o caminho especificado, o modo de criação, a permissão de leitura/gravação e compartilhamento, o tamanho do buffer, opções de arquivo adicionais, o tamanho da pré-alocação e o acesso que outros FileStreams podem ter para o mesmo arquivo.

Propriedades

Nome	Description
CanRead	Obtém um valor que indica se o fluxo atual dá suporte à leitura.
CanSeek	Obtém um valor que indica se o fluxo atual dá suporte à busca.
CanTimeout	Obtém um valor que determina se o fluxo atual pode acabar. (Herdado de Stream)
CanWrite	Obtém um valor que indica se o fluxo atual dá suporte à gravação.
Handle	Obsoleto. Obtém o identificador de arquivo do sistema operacional para o arquivo encapsulado pelo objeto atual FileStream .
IsAsync	Obtém um valor que indica se o FileStream foi aberto de forma assíncrona ou síncrona.
Length	Obtém o comprimento em bytes do fluxo.
Name	Obtém o caminho absoluto do arquivo aberto no FileStream.
Position	Obtém ou define a posição atual desse fluxo.
ReadTimeout	Obtém ou define um valor, em milissegundos, que determina quanto tempo o fluxo tentará ler antes do tempo limite. (Herdado de Stream)
SafeFileHandle	Obtém um SafeFileHandle objeto que representa o identificador de arquivo do sistema operacional para o arquivo encapsulado pelo objeto atual FileStream .
WriteTimeout	Obtém ou define um valor, em milissegundos, que determina por quanto tempo o fluxo tentará gravar antes do tempo limite. (Herdado de Stream)

Métodos

Nome	Description
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	Inicia uma operação de leitura assíncrona. Considere o uso de ReadAsync(Byte[], Int32, Int32, CancellationToken) em seu lugar.
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	Inicia uma operação de gravação assíncrona. Considere o uso de WriteAsync(Byte[], Int32, Int32, CancellationToken) em seu lugar.
Close()	Fecha o fluxo atual e libera todos os recursos (como soquetes e identificadores de arquivo) associados ao fluxo atual. Em vez de chamar esse método, verifique se o fluxo foi descartado corretamente. (Herdado de Stream)
CopyTo(Stream, Int32)	Lê os bytes do fluxo atual e os grava em outro fluxo, usando um tamanho de buffer especificado. Ambas as posições de fluxos são avançadas pelo número de bytes copiados.
CopyTo(Stream)	Lê os bytes do fluxo atual e os grava em outro fluxo. Ambas as posições de fluxos são avançadas pelo número de bytes copiados. (Herdado de Stream)
CopyToAsync(Stream, CancellationToken)	Lê assíncronamente os bytes do fluxo atual e os grava em outro fluxo, usando um token de cancelamento especificado. Ambas as posições de fluxos são avançadas pelo número de bytes copiados. (Herdado de Stream)
CopyToAsync(Stream, Int32, CancellationToken)	Lê assíncronamente os bytes do fluxo de arquivos atual e os grava em outro fluxo, usando um token de cancelamento e tamanho de buffer especificado.
CopyToAsync(Stream, Int32)	Lê de forma assíncrona os bytes do fluxo atual e os grava em outro fluxo, usando um tamanho de buffer especificado. Ambas as posições de fluxos são avançadas pelo número de bytes copiados. (Herdado de Stream)
CopyToAsync(Stream)	Lê assíncronamente os bytes do fluxo atual e os grava em outro fluxo. Ambas as posições de fluxos são avançadas pelo número de bytes copiados. (Herdado de Stream)
CreateWaitHandle()	Obsoleto. Aloca um WaitHandle objeto. (Herdado de Stream)
Dispose()	Libera todos os recursos usados pelo Stream. (Herdado de Stream)
Dispose(Boolean)	Libera os recursos não gerenciados usados pelo FileStream e, opcionalmente, libera os recursos gerenciados.
DisposeAsync()	Libera de forma assíncrona os recursos não gerenciados usados pelo FileStream.
EndRead(IAsyncResult)	Aguarda a conclusão da operação de leitura assíncrona pendente. (Considere usar ReadAsync(Byte[], Int32, Int32, CancellationToken) em vez disso.)
EndWrite(IAsyncResult)	Encerra uma operação de gravação assíncrona e bloqueia até que a operação de E/S seja concluída. (Considere usar WriteAsync(Byte[], Int32, Int32, CancellationToken) em vez disso.)
Equals(Object)	Determina se o objeto especificado é igual ao objeto atual. (Herdado de Object)
Finalize()	Garante que os recursos sejam liberados e outras operações de limpeza sejam executadas quando o coletor de lixo recuperar o FileStream.
Flush()	Limpa os buffers desse fluxo e faz com que todos os dados em buffer sejam gravados no arquivo.
Flush(Boolean)	Limpa os buffers desse fluxo e faz com que todos os dados em buffer sejam gravados no arquivo e também limpa todos os buffers de arquivos intermediários.
FlushAsync()	Limpa de forma assíncrona todos os buffers para esse fluxo e faz com que todos os dados em buffer sejam gravados no dispositivo subjacente. (Herdado de Stream)
FlushAsync(CancellationToken)	Limpa de forma assíncrona todos os buffers para esse fluxo, faz com que todos os dados em buffer sejam gravados no arquivo e monitora solicitações de cancelamento.
GetHashCode()	Serve como a função de hash padrão. (Herdado de Object)
GetLifetimeService()	Obsoleto. Recupera o objeto de serviço de tempo de vida atual que controla a política de tempo de vida para essa instância. (Herdado de MarshalByRefObject)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
InitializeLifetimeService()	Obsoleto. Obtém um objeto de serviço de tempo de vida para controlar a política de tempo de vida dessa instância. (Herdado de MarshalByRefObject)
Lock(Int64, Int64)	Impede que outros processos leiam ou gravem no FileStream.
MemberwiseClone()	Cria uma cópia superficial do Objectatual. (Herdado de Object)
MemberwiseClone(Boolean)	Cria uma cópia superficial do objeto atual MarshalByRefObject . (Herdado de MarshalByRefObject)
ObjectInvariant()	Obsoleto. Fornece suporte para um Contract. (Herdado de Stream)
Read(Byte[], Int32, Int32)	Lê um bloco de bytes do fluxo e grava os dados em um determinado buffer.
Read(Span<Byte>)	Lê uma sequência de bytes do fluxo de arquivos atual e avança a posição dentro do fluxo de arquivos pelo número de bytes lidos.
ReadAsync(Byte[], Int32, Int32, CancellationToken)	Lê de forma assíncrona uma sequência de bytes do fluxo de arquivos atual e os grava em uma matriz de bytes começando em um deslocamento especificado, avança a posição dentro do fluxo de arquivos pelo número de bytes lidos e monitora solicitações de cancelamento.
ReadAsync(Byte[], Int32, Int32)	Lê de forma assíncrona uma sequência de bytes do fluxo atual e avança a posição dentro do fluxo pelo número de bytes lidos. (Herdado de Stream)
ReadAsync(Memory<Byte>, CancellationToken)	Lê de forma assíncrona uma sequência de bytes do fluxo de arquivos atual e os grava em uma região de memória, avança a posição dentro do fluxo de arquivos pelo número de bytes lidos e monitora solicitações de cancelamento.
ReadAtLeast(Span<Byte>, Int32, Boolean)	Lê pelo menos um número mínimo de bytes do fluxo atual e avança a posição dentro do fluxo pelo número de bytes lidos. (Herdado de Stream)
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)	Lê de forma assíncrona pelo menos um número mínimo de bytes do fluxo atual, avança a posição dentro do fluxo pelo número de bytes lidos e monitora solicitações de cancelamento. (Herdado de Stream)
ReadByte()	Lê um byte do arquivo e avança a posição de leitura um byte.
ReadExactly(Byte[], Int32, Int32)	Lê count o número de bytes do fluxo atual e avança a posição dentro do fluxo. (Herdado de Stream)
ReadExactly(Span<Byte>)	Lê bytes do fluxo atual e avança a posição dentro do fluxo até que ela buffer seja preenchida. (Herdado de Stream)
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	Lê count de forma assíncrona o número de bytes do fluxo atual, avança a posição dentro do fluxo e monitora solicitações de cancelamento. (Herdado de Stream)
ReadExactlyAsync(Memory<Byte>, CancellationToken)	Lê bytes de forma assíncrona do fluxo atual, avança a posição dentro do fluxo até que ele buffer seja preenchido e monitore as solicitações de cancelamento. (Herdado de Stream)
Seek(Int64, SeekOrigin)	Define a posição atual desse fluxo como o valor fornecido.
SetLength(Int64)	Define o comprimento desse fluxo como o valor fornecido.
ToString()	Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object)
Unlock(Int64, Int64)	Permite o acesso de outros processos a todos ou parte de um arquivo que foi bloqueado anteriormente.
Write(Byte[], Int32, Int32)	Grava um bloco de bytes no fluxo de arquivos.
Write(ReadOnlySpan<Byte>)	Grava uma sequência de bytes de um intervalo somente leitura para o fluxo de arquivos atual e avança a posição atual dentro desse fluxo de arquivos pelo número de bytes gravados.
WriteAsync(Byte[], Int32, Int32, CancellationToken)	Grava de forma assíncrona uma sequência de bytes no fluxo atual, avança a posição atual dentro desse fluxo pelo número de bytes gravados e monitora solicitações de cancelamento.
WriteAsync(Byte[], Int32, Int32)	Grava de forma assíncrona uma sequência de bytes no fluxo atual e avança a posição atual dentro desse fluxo pelo número de bytes gravados. (Herdado de Stream)
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	Grava de forma assíncrona uma sequência de bytes de uma região de memória no fluxo de arquivos atual, avança a posição atual nesse fluxo de arquivos pelo número de bytes gravados e monitora solicitações de cancelamento.
WriteByte(Byte)	Grava um byte na posição atual no fluxo de arquivos.

Métodos de Extensão

Nome	Description
ConfigureAwait(IAsyncDisposable, Boolean)	Configura como as esperas nas tarefas retornadas de um descartável assíncrono serão executadas.
CopyToAsync(Stream, PipeWriter, CancellationToken)	Lê de forma assíncrona os bytes e Stream os grava no especificado PipeWriter, usando um token de cancelamento.
GetAccessControl(FileStream)	Retorna as informações de segurança de um arquivo.
SetAccessControl(FileStream, FileSecurity)	Altera os atributos de segurança de um arquivo existente.

Confira também

• File
• FileAccess
• FileMode
• FileShare
• E/S de arquivo e de fluxo
• Como ler texto de um arquivo
• Como gravar texto em um arquivo
• Como ler e gravar em um arquivo de dados recém-criado