FileStream Classe

Definição

Espaço de Nomes:

System.IO

Assemblagens:

netstandard.dll, System.Runtime.dll

Origem:

FileStream.cs

Fornece um Stream para um ficheiro, suportando operações de leitura e escrita 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 seguinte 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 seguinte mostra como escrever num ficheiro de forma assíncrona. Este código corre numa aplicação WPF que tem um TextBlock chamado UserInput e um botão ligado a um handler de eventos Click que se chama Button_Click. O caminho do ficheiro precisa de ser alterado para um ficheiro que exista 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

Observações

Use a FileStream classe para ler, gravar, abrir e fechar arquivos em um sistema de arquivos e para 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 , Write, CopyToe Flush para executar operações síncronas, ou os métodos , ReadAsync, WriteAsynce CopyToAsync para executar operações assíncronasFlushAsync. Use os métodos assíncronos para executar operações de arquivo que consomem muitos recursos sem bloquear o thread principal. Esta consideração de desempenho é particularmente importante numa aplicação de ambiente de trabalho, onde uma operação de stream demorada pode bloquear o thread da interface e fazer com que a sua aplicação pareça que não está a funcionar. FileStream Buffers de entrada e saída para um melhor desempenho.

Importante

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

A IsAsync propriedade deteta se o identificador de arquivo foi aberto de forma assíncrona. Você especifica esse valor quando cria uma instância da FileStream classe usando um construtor que tem um isAsyncparâmetro , useAsync, ou options . Quando a propriedade é true, o fluxo utiliza E/S sobrepostas para executar operações de arquivo de forma assíncrona. No entanto, a IsAsync propriedade não precisa ser true para chamar o ReadAsyncWriteAsync, , ou CopyToAsync método. Quando a IsAsync propriedade é false e você chama as operações assíncronas de leitura e gravação, o thread da interface do usuário ainda não está bloqueado, mas a operação de E/S real é executada de forma síncrona.

O Seek método suporta 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 deslocamento de byte. O deslocamento de byte é 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 SeekOrigin enumeração.

Note

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

Se um processo termina com parte de um arquivo bloqueado ou fecha um arquivo que tem bloqueios pendentes, o comportamento é indefinido.

Para operações de diretório e outras operações de arquivo, consulte as Fileclasses , Directorye 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 a partir de uma matriz de bytes e é semelhante à FileStream classe.

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

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

Quando um FileStream objeto não tem uma retenção exclusiva sobre o seu manípulo, outro thread pode aceder ao manípulo de ficheiro simultaneamente e alterar a posição do ponteiro de ficheiro do sistema operativo associado ao manípulo de ficheiro. Nesse caso, a posição em cache no FileStream objeto e os dados armazenados em cache no buffer podem ser comprometidos. O objeto FileStream executa rotineiramente verificações em métodos que acessam o buffer armazenado em cache para garantir que a posição do manipulador do sistema operativo seja a mesma que a posição em cache usada pelo objeto FileStream.

Se uma alteração inesperada na posição do identificador for detetada numa chamada para o método Read, o .NET descartará o conteúdo do buffer e lerá o fluxo do ficheiro novamente. Isso pode afetar o desempenho, dependendo do tamanho do arquivo e de quaisquer outros processos que possam afetar a posição do fluxo de arquivos.

Se uma alteração inesperada na posição do manípulo for detetada durante uma chamada ao Write método, o conteúdo do buffer será descartado e uma IOException exceção será lançada.

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

Construtores

Name	Descrição
FileStream(IntPtr, FileAccess, Boolean, Int32, Boolean)	Obsoleto. Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita especificada, FileStream propriedade da instância, tamanho do buffer e estado síncrono ou assíncrono.
FileStream(IntPtr, FileAccess, Boolean, Int32)	Obsoleto. Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita especificada, FileStream propriedade da instância e tamanho do buffer.
FileStream(IntPtr, FileAccess, Boolean)	Obsoleto. Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita e FileStream a propriedade da instância especificadas.
FileStream(IntPtr, FileAccess)	Obsoleto. Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita especificada.
FileStream(SafeFileHandle, FileAccess, Int32, Boolean)	Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita especificada, tamanho do buffer e estado síncrono ou assíncrono.
FileStream(SafeFileHandle, FileAccess, Int32)	Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita e o tamanho do buffer especificados.
FileStream(SafeFileHandle, FileAccess)	Inicializa uma nova instância da FileStream classe para o handle de ficheiro especificado, com a permissão de leitura/escrita especificada.
FileStream(String, FileMode, FileAccess, FileShare, Int32, Boolean)	Inicializa uma nova instância da FileStream classe com o caminho especificado, modo de criação, permissões de leitura/escrita e partilha, tamanho do buffer e 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, modo de criação, permissão de leitura/escrita e partilha, o acesso a outros FileStreams ao mesmo ficheiro, o tamanho do buffer e opções adicionais de ficheiro.
FileStream(String, FileMode, FileAccess, FileShare, Int32)	Inicializa uma nova instância da FileStream classe com o caminho especificado, modo de criação, permissão de leitura/escrita e partilha, e tamanho do buffer.
FileStream(String, FileMode, FileAccess, FileShare)	Inicializa uma nova instância da FileStream classe com o caminho especificado, modo de criação, permissão de leitura/escrita e permissão de partilha.
FileStream(String, FileMode, FileAccess)	Inicializa uma nova instância da FileStream classe com o caminho especificado, modo de criação e permissão de leitura/escrita.
FileStream(String, FileMode)	Inicializa uma nova instância da FileStream classe com o caminho e modo de criação especificados.
FileStream(String, FileStreamOptions)	Inicializa uma nova instância da FileStream classe com o caminho especificado, modo de criação, permissão de leitura/escrita e partilha, tamanho do buffer, opções adicionais de ficheiro, tamanho de pré-alocação e o acesso que outros FileStreams podem ter ao mesmo ficheiro.

Propriedades

Name	Descrição
CanRead	Recebe um valor que indica se o fluxo atual suporta leitura.
CanSeek	Obtém um valor que indica se o fluxo atual suporta procura.
CanTimeout	Obtém um valor que determina se o fluxo atual pode expirar. (Herdado de Stream)
CanWrite	Obtém um valor que indica se o fluxo atual suporta escrita.
Handle	Obsoleto. Obtém o handle do ficheiro do sistema operativo para o ficheiro que o objeto atual FileStream encapsula.
IsAsync	Obtém um valor que indica se foi FileStream aberto de forma assíncrona ou síncrona.
Length	Obtém o comprimento em bytes do fluxo.
Name	Obtém o caminho absoluto do ficheiro aberto no FileStreamarquivo .
Position	Obtém ou define a posição atual deste fluxo.
ReadTimeout	Recebe ou define um valor, em milissegundos, que determina quanto tempo o fluxo tentará ler antes de expirar. (Herdado de Stream)
SafeFileHandle	Obtém um SafeFileHandle objeto que representa o handle do ficheiro do sistema operativo para o ficheiro que o objeto atual FileStream encapsula.
WriteTimeout	Recebe ou define um valor, em milissegundos, que determina quanto tempo o fluxo tenta escrever antes de expirar. (Herdado de Stream)

Métodos

Name	Descrição
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	Inicia uma operação de leitura assíncrona. Em vez disso, considere usar ReadAsync(Byte[], Int32, Int32, CancellationToken).
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	Inicia uma operação de escrita assíncrona. Em vez disso, considere usar WriteAsync(Byte[], Int32, Int32, CancellationToken).
Close()	Fecha o fluxo atual e liberta quaisquer recursos (como sockets e handles de ficheiros) associados ao fluxo atual. Em vez de chamar este método, certifique-se de que o fluxo é devidamente descartado. (Herdado de Stream)
CopyTo(Stream, Int32)	Lê os bytes do fluxo atual e escreve-os noutro fluxo, usando um tamanho de buffer especificado. As posições de ambos os fluxos são avançadas pelo número de bytes copiados.
CopyTo(Stream)	Lê os bytes do fluxo atual e escreve-os noutro fluxo. As posições de ambos os 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 escreve-os noutro fluxo, usando um token de cancelamento especificado. As posições de ambos os 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 ficheiros atual e escreve-os noutro fluxo, usando um tamanho de buffer especificado e um token de cancelamento.
CopyToAsync(Stream, Int32)	Lê assíncronamente os bytes do fluxo atual e escreve-os noutro fluxo, usando um tamanho de buffer especificado. As posições de ambos os 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 escreve-os noutro fluxo. As posições de ambos os fluxos são avançadas pelo número de bytes copiados. (Herdado de Stream)
CreateWaitHandle()	Obsoleto. Aloca um WaitHandle objeto. (Herdado de Stream)
Dispose()	Liberta todos os recursos utilizados pelo Stream. (Herdado de Stream)
Dispose(Boolean)	Liberta os recursos não geridos usados pelo FileStream e opcionalmente liberta os recursos geridos.
DisposeAsync()	De forma assíncrona, liberta os recursos não geridos usados pelos FileStream.
EndRead(IAsyncResult)	Espera que a operação de leitura assíncrona pendente seja concluída. (Considere usar ReadAsync(Byte[], Int32, Int32, CancellationToken) em vez disso.)
EndWrite(IAsyncResult)	Termina uma operação de escrita assíncrona e bloqueia até que a operação de E/S esteja completa. (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()	Assegura que os recursos são libertados e que outras operações de limpeza são realizadas quando o coletor de lixo recupera o FileStream.
Flush()	Limpa buffers para este fluxo e faz com que quaisquer dados armazenados sejam escritos no ficheiro.
Flush(Boolean)	Limpa buffers para este fluxo e faz com que quaisquer dados armazenados sejam escritos no ficheiro, além de limpar todos os buffers intermédios de ficheiros.
FlushAsync()	Apaga assíncronamente todos os buffers deste fluxo e faz com que quaisquer dados armazenados sejam escritos no dispositivo subjacente. (Herdado de Stream)
FlushAsync(CancellationToken)	O processo asíncrono limpa todos os buffers deste fluxo, faz com que quaisquer dados armazenados no ficheiro sejam escritos no ficheiro e monitoriza pedidos de cancelamento.
GetHashCode()	Serve como função de hash predefinida. (Herdado de Object)
GetLifetimeService()	Obsoleto. Recupera o objeto de serviço de tempo de vida atual que controla a política de vida útil neste caso. (Herdado de MarshalByRefObject)
GetType()	Obtém o Type da instância atual. (Herdado de Object)
InitializeLifetimeService()	Obsoleto. Obtém-se um objeto de serviço vitalício para controlar a apólice vitalícia neste caso. (Herdado de MarshalByRefObject)
Lock(Int64, Int64)	Impede que outros processos leiam ou escrevam no FileStream.
MemberwiseClone()	Cria uma cópia superficial do atual Object. (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 escreve os dados num dado buffer.
Read(Span<Byte>)	Lê uma sequência de bytes do fluxo de ficheiros atual e avança a posição dentro do fluxo pelo número de bytes lidos.
ReadAsync(Byte[], Int32, Int32, CancellationToken)	Lê assíncronamente uma sequência de bytes do fluxo de ficheiros atual e escreve-os num array de bytes a partir de um deslocamento especificado, avança a posição dentro do fluxo de ficheiros pelo número de bytes lidos e monitoriza pedidos de cancelamento.
ReadAsync(Byte[], Int32, Int32)	A leitura 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)	A leitura assíncrona uma sequência de bytes do fluxo de ficheiros atual e escreve-os numa região de memória, avança a posição dentro do fluxo de ficheiros pelo número de bytes lidos e monitoriza pedidos 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)	O Assíncrono lê 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 monitoriza pedidos de cancelamento. (Herdado de Stream)
ReadByte()	Lê um byte do ficheiro 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é ser buffer preenchido. (Herdado de Stream)
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	Lê count assíncronamente o número de bytes do fluxo atual, avança a posição dentro do fluxo e monitoriza pedidos de cancelamento. (Herdado de Stream)
ReadExactlyAsync(Memory<Byte>, CancellationToken)	Lê assíncronamente bytes do fluxo atual, avança a posição dentro do fluxo até que este buffer seja preenchido e monitoriza pedidos de cancelamento. (Herdado de Stream)
Seek(Int64, SeekOrigin)	Define a posição atual deste fluxo para o valor dado.
SetLength(Int64)	Define o comprimento deste fluxo para o valor dado.
ToString()	Devolve uma cadeia que representa o objeto atual. (Herdado de Object)
Unlock(Int64, Int64)	Permite o acesso de outros processos a todo ou parte de um ficheiro que estava previamente bloqueado.
Write(Byte[], Int32, Int32)	Escreve um bloco de bytes no fluxo de ficheiros.
Write(ReadOnlySpan<Byte>)	Escreve uma sequência de bytes de um intervalo de apenas leitura para o fluxo de ficheiros atual e avança a posição atual dentro desse fluxo pelo número de bytes escritos.
WriteAsync(Byte[], Int32, Int32, CancellationToken)	Escreve assíncronamente uma sequência de bytes no fluxo atual, avança a posição atual dentro deste fluxo pelo número de bytes escritos e monitoriza pedidos de cancelamento.
WriteAsync(Byte[], Int32, Int32)	Escreve assíncronamente uma sequência de bytes no fluxo atual e avança a posição atual dentro desse fluxo pelo número de bytes escritos. (Herdado de Stream)
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	Escreve assíncronamente uma sequência de bytes de uma região de memória para o fluxo de ficheiros atual, avança a posição atual dentro desse fluxo de ficheiros pelo número de bytes escritos e monitoriza pedidos de cancelamento.
WriteByte(Byte)	Escreve um byte na posição atual no fluxo de ficheiros.

Métodos da Extensão

Name	Descrição
ConfigureAwait(IAsyncDisposable, Boolean)	Configura como aguarda nas tarefas devolvidas de um descartável assíncrono será realizada.
CopyToAsync(Stream, PipeWriter, CancellationToken)	Lê assíncronamente os bytes do Stream e escreve-os no especificado PipeWriter, usando um token de cancelamento.
GetAccessControl(FileStream)	Devolve a informação de segurança de um ficheiro.
SetAccessControl(FileStream, FileSecurity)	Altera os atributos de segurança de um ficheiro existente.

Ver também

• File
• FileAccess
• FileMode
• FileShare
• E/S de arquivo e 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