Add isAsync overload for Create/Open/etc.

[Duranom]

Background and Motivation

When using System.IO.File and/or System.IO.FileInfo for opening, creating and writing files you do not have the option to properly open FileStreams for use with async methods.

A very common mistake/issue that occurs because of it is that files are opened through methods like File.OpenWrite or new FileInfo(x).Open() and the FileStream is then used with async/await operations like WriteAsync or ReadAsync. However when this is done you will incur a performance hit as the stream is not configured to be used in this way.

The proper way to use FileStreams with async await is to open a FileStream through the constructor with and supplying the argument isAsync with true. However System.IO.File and System.IO.FileInfo expose a lot of convenient shorthands but lack the possibility to open the streams properly for async actions. leading also to the misconception that async await with file IO is actually not good.

Proposed API

@adamsitnik proposed the use of a FileOptions and supply additional overloads to System.IO.StreamReader, System.IO.StreamWriter , System.IO.File and System.IO.FileInfo so not only Files can be opened with FileOptions.Asynchronous but also with FileOptions.SequentialScan.
Comment: #24698 (comment)

public static partial class File
{
    public StreamWriter AppendText(string path)
+   public StreamWriter AppendText(string path, FileOptions options)
    public static System.IO.FileStream Create(string path)
+   public static System.IO.FileStream Create(string path, System.IO.FileOptions options)
    public static System.IO.FileStream Create(string path, int bufferSize)
    public static System.IO.FileStream Create(string path, int bufferSize, System.IO.FileOptions options)
    public static System.IO.StreamWriter CreateText(string path)
+   public static System.IO.StreamWriter CreateText(string path, System.IO.FileOptions options)   
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileOptions options)
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileOptions options)
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share, System.IO.FileOptions options)
    public static System.IO.FileStream OpenRead(string path) { throw null; }
+   public static System.IO.FileStream OpenRead(string path, System.IO.FileOptions options) { throw null; }
    public static System.IO.StreamReader OpenText(string path) { throw null; }
+   public static System.IO.StreamReader OpenText(string path, System.IO.FileOptions options) { throw null; }
    public static System.IO.FileStream OpenWrite(string path) { throw null; }
+   public static System.IO.FileStream OpenWrite(string path, System.IO.FileOptions options) { throw null; }
}

note that File.Create(string path, int bufferSize, System.IO.FileOptions options) already exists.

public sealed partial class FileInfo : System.IO.FileSystemInfo
{
    public StreamWriter AppendText()
+   public StreamWriter AppendText(FileOptions options)
    public System.IO.FileStream Create()
+   public System.IO.FileStream Create(System.IO.FileOptions options)
    public System.IO.StreamWriter CreateText()
+   public System.IO.StreamWriter CreateText(System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share, System.IO.FileOptions options)
    public System.IO.FileStream OpenRead()
+   public System.IO.FileStream OpenRead(System.IO.FileOptions options)
    public System.IO.StreamReader OpenText()
+   public System.IO.StreamReader OpenText(System.IO.FileOptions options)    
    public System.IO.FileStream OpenWrite()
+   public System.IO.FileStream OpenWrite(System.IO.FileOptions options)
}

public partial class StreamReader : System.IO.TextReader
{
    public StreamReader(string path)
+   public StreamReader(string path, System.IO.FileOptions options)
    public StreamReader(string path, bool detectEncodingFromByteOrderMarks)
+   public StreamReader(string path, bool detectEncodingFromByteOrderMarks, System.IO.FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding)
+   public StreamReader(string path, System.Text.Encoding encoding, System.IO.FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks)
+   public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, System.IO.FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize)
+   public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize, System.IO.FileOptions options)
}

public partial class StreamWriter : System.IO.TextWriter
{
    public StreamWriter(string path)
+   public StreamWriter(string path, System.IO.FileOptions options)
    public StreamWriter(string path, bool append)
+   public StreamWriter(string path, bool append, System.IO.FileOptions options)
    public StreamWriter(string path, bool append, System.Text.Encoding encoding)
+   public StreamWriter(string path, bool append, System.Text.Encoding encoding, System.IO.FileOptions options)
    public StreamWriter(string path, bool append, System.Text.Encoding encoding, int bufferSize)
+   public StreamWriter(string path, bool append, System.Text.Encoding encoding, int bufferSize, System.IO.FileOptions options)
}

Usage Examples

using FileStream filestream = File.OpenRead(Path.GetTempFileName(), FileOptions.Asynchronous);
byte[] bytes = Encoding.Unicode.GetBytes("example text to write");
await filestream.WriteAsync(bytes, 0, bytes.Length);

Alternative Designs

In the beginning an idea was put for exposing additional async API methods next to the existing methods and that would return return the stream in a Task / ValueTask and guide the developer immediately into the async environment, also taken into account that a lot of .NET Native only exposed async variants in the API's with IO file streams.
However as was mentioned in comments that streams are opened with constructors and would require a lot of changes and provide no additional benefit and more overhead.

Risks

[Duranom]

Btw is there still a big requirement to have Filestreams by default not open for asynchronous operations?
As the performance hit is a lot less with synchronous operations on streams that are opened for asynchronous operations then it is the other way around.

[adamsitnik]

The proper way to use FileStreams with async await is to open the FileStream through the constructor with argument isAsync to true. However as File and FileInfo are more directly approached and provide easier shorthands for common actions the mistake is made often. Besides the performance hit this also creates a big misconception that async await with file IO is actually not good.

I agree that we should make it easier to open|create files for async IO. Especially since we want to invest in FileStream in .NET 6.0.

If an async variant could be added like File.OpenAsync,

The Async suffix suggests that given operation is asynchronous and returns a Task. As of today, the only way to open FileStream for async IO is to pass the right flag to the synchronous ctor.
Since FileStream does not offer any async API for opening files, I would prefer to not choose this solution (as it would require big changes in FileStream).

or have and variant with an added an argument like File.Open(bool isAsync)

I like File.Open(bool isAsync) because it's simple, but to make it more flexible we could add an overload that accepts FileOptions, which can be set to not just FileOptions.Asynchronous but can also be combined with other options like FileOptions.SequentialScan

Since File and FileInfo APIs rely heavily on StreamReader and StreamWriter we are going to need new ctors for these types:

public partial class StreamReader : System.IO.TextReader
{
    public StreamReader(string path)
+   public StreamReader(string path, System.IO.FileOptions options)
    public StreamReader(string path, bool detectEncodingFromByteOrderMarks)
+   public StreamReader(string path, bool detectEncodingFromByteOrderMarks,System.IO. FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding)
+   public StreamReader(string path, System.Text.Encoding encoding, System.IO.FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks)
+   public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, System.IO.FileOptions options)
    public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize)
+   public StreamReader(string path, System.Text.Encoding encoding, bool detectEncodingFromByteOrderMarks, int bufferSize, System.IO.FileOptions options)
}

public partial class StreamWriter : System.IO.TextWriter
{
    public StreamWriter(string path)
+   public StreamWriter(string path, System.IO.FileOptions options)
    public StreamWriter(string path, bool append)
+   public StreamWriter(string path, bool append, System.IO.FileOptions options)
    public StreamWriter(string path, bool append, System.Text.Encoding encoding)
+   public StreamWriter(string path, bool append, System.Text.Encoding encoding, System.IO.FileOptions options)
    public StreamWriter(string path, bool append, System.Text.Encoding encoding, int bufferSize)
+   public StreamWriter(string path, bool append, System.Text.Encoding encoding, int bufferSize, System.IO.FileOptions options)
}

This should allow for:

public static partial class File
{
    public static System.IO.FileStream Create(string path)
+   public static System.IO.FileStream Create(string path, System.IO.FileOptions options)
    public static System.IO.FileStream Create(string path, int bufferSize)
    public static System.IO.FileStream Create(string path, int bufferSize, System.IO.FileOptions options)
    public static System.IO.StreamWriter CreateText(string path)
+   public static System.IO.StreamWriter CreateText(string path, System.IO.FileOptions options)   
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileOptions options)
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileOptions options)
    public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share)
+   public static System.IO.FileStream Open(string path, System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share, System.IO.FileOptions options)
    public static System.IO.FileStream OpenRead(string path) { throw null; }
+   public static System.IO.FileStream OpenRead(string path) { throw null; }
    public static System.IO.StreamReader OpenText(string path) { throw null; }
+   public static System.IO.StreamReader OpenText(string path) { throw null; }
    public static System.IO.FileStream OpenWrite(string path) { throw null; }
+   public static System.IO.FileStream OpenWrite(string path) { throw null; }
}

note that File.Create(string path, int bufferSize, System.IO.FileOptions options) already exists.

public sealed partial class FileInfo : System.IO.FileSystemInfo
{
    public System.IO.FileStream Create()
+   public System.IO.FileStream Create(System.IO.FileOptions options)
    public System.IO.StreamWriter CreateText()
+   public System.IO.StreamWriter CreateText(System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileOptions options)
    public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share)
+   public System.IO.FileStream Open(System.IO.FileMode mode, System.IO.FileAccess access, System.IO.FileShare share, System.IO.FileOptions options)
    public System.IO.FileStream OpenRead()
+   public System.IO.FileStream OpenRead(System.IO.FileOptions options)
    public System.IO.StreamReader OpenText()
+   public System.IO.StreamReader OpenText(System.IO.FileOptions options)    
    public System.IO.FileStream OpenWrite()
+   public System.IO.FileStream OpenWrite(System.IO.FileOptions options)
}

@Duranom would the proposed API meet your needs?

@carlossanlop @jozkee since this task aligns with our .NET 6.0 goals, I am setting the 6.0 milestone for it

[Duranom]

Yes, think that will help with the misconception.

note that File.Create(string path, int bufferSize, System.IO.FileOptions options) already exists.

Just wondering how many use this and set the buffersize to 4096 (the default), think the File.Create(string path, System.IO.FileOptions options) would only be missing then.

[adamsitnik]

think the File.Create(string path, System.IO.FileOptions options) would only be missing then

@Duranom good point! thank you for feedback!

@Duranom some time ago we have added an official template for API proposal. Is there any chance that you could update your issue description and fill the template? Then I would mark it as ready for review, introduce it in .NET Design Review Meeting and once we get the API approved, we can start coding and ship it ;)

[Duranom]

Updated, apologies for delay

[adamsitnik]

@Duranom thank you!