FileStreamOptions.PreallocationSize Propriedade

Definição

Namespace:

System.IO

Assembly:

System.Runtime.dll

Origem:

FileStreamOptions.cs

O tamanho da alocação inicial em bytes para o arquivo. Um valor positivo só é eficaz quando um arquivo regular está sendo criado ou substituído (Create ou CreateNew). Valores negativos não são permitidos. Em outros casos (incluindo o valor padrão 0), ele é ignorado. Esse valor é uma dica e não é uma garantia forte. Não há suporte para ele no WASM (Web Assembly) e no FreeBSD (o valor é ignorado). Para Windows, Linux e macOS, tentaremos pré-alocar o espaço em disco para preencher o tamanho de alocação solicitado. Se isso for impossível, a operação gerará uma exceção. O EOF (comprimento final do arquivo) será determinado pelo número de bytes gravados no arquivo.

public:
 property long PreallocationSize { long get(); void set(long value); };

public long PreallocationSize { get; set; }

member this.PreallocationSize : int64 with get, set

Public Property PreallocationSize As Long

Valor da propriedade

Int64

Um número não negativo que representa o tamanho da alocação inicial em bytes para o arquivo.

Exceções

ArgumentOutOfRangeException

Quando value é negativo.

Exemplos

O exemplo de código a seguir demonstra como usar PreallocationSize ao trabalhar com FileStream objetos:

using System.IO;

public static class PreallocationSizeExample
{
    public static void Main()
    {
        string destinationPath = "destination.dll";

        var openForReading = new FileStreamOptions { Mode = FileMode.Open };
        using var source = new FileStream(typeof(PreallocationSizeExample).Assembly.Location, openForReading);

        var createForWriting = new FileStreamOptions
        {
            Mode = FileMode.CreateNew,
            Access = FileAccess.Write,
            PreallocationSize = source.Length // specify size up-front
        };
        using var destination = new FileStream(destinationPath, createForWriting);

        source.CopyTo(destination); // copies the contents of the assembly file into the destination file
    }
}

Imports System.IO

Module PreallocationSizeExample

    Sub Main()

        Dim destinationPath As String = "destination.dll"
        Dim openForReading = New FileStreamOptions With {
            .Mode = FileMode.Open
        }

        Using source = New FileStream(GetType(PreallocationSizeExample).Assembly.Location, openForReading)

            Dim createForWriting = New FileStreamOptions With {
                .Mode = FileMode.CreateNew,
                .Access = FileAccess.Write,
                .PreallocationSize = source.Length ' specify size up-front
            }

            Using destination = New FileStream(destinationPath, createForWriting)
                source.CopyTo(destination) ' copies the contents of the assembly file into the destination file
            End Using

        End Using

    End Sub

End Module

Comentários

PreallocationSize só pode ser solicitado para o modo de gravação (Access deve ser definido Writecomo ) e ao criar novos arquivos (Mode deve ser definido como Create ou como CreateNew). Caso contrário, o FileStream construtor gerará uma exceção.

Se o sistema operacional, a plataforma ou o sistema de arquivos não der suporte à pré-alocação, será PreallocationSize ignorado. Esse é o caso de WASM (Web Assembly) e FreeBSD.

Se não houver espaço em disco suficiente ou o sistema de arquivos não oferecer suporte a arquivos de determinado tamanho (exemplo: arquivo de 5 GB no FAT32), uma exceção será gerada.

O comprimento do arquivo é determinado por quantos bytes foram gravados no arquivo.

Quando o arquivo é fechado e nem todo o espaço alocado é gravado, o que acontece com o espaço restante depende da plataforma. No Windows, esse espaço não é mais reservado para o arquivo. Em outras plataformas, como Linux e macOS, ele permanece alocado para o arquivo.

Por exemplo, suponha que 2 GB seja pré-alocado para um arquivo, mas apenas 1 GB seja gravado. Depois de fechar o arquivo, o comprimento do arquivo é de 1 GB em todos os sistemas operacionais. No Windows, o tamanho alocado também é de 1 GB, mas no Linux e no macOS, o tamanho alocado ainda é de 2 GB.

É permitido escrever mais do que o que foi pré-alocado inicialmente. Desde que haja espaço em disco suficiente, a operação deverá ser bem-sucedida.