Classe System.IO.FileStream

Este artigo fornece comentários complementares à documentação de referência para esta API.

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 sobre o desempenho é particularmente importante em um aplicativo da Microsoft Store 8.x ou aplicativo de desktop em que uma operação demorada de fluxo pode bloquear o thread de interface do usuário e fazer seu aplicativo parecer como se não estivesse funcionando. FileStream armazena dados de entrada e saída para melhor desempenho.

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.

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.