Standardize the behavior of CreateFile/CreateFolder across different OS

[Frederisk]

What does the pull request do?

Currently, Avalonia only provides a very simple wrapper for system I/O. This results in significant behavioral differences in the same I/O method across different operating systems, which may lead to unexpected operations.

This PR aims to standardize the differences in method behavior across different platforms, starting with creating files and folders. Specifically, the approach here targets .NET's FileInfo.Create() and DirectoryInfo.CreateSubdirectory() methods to achieve similar interface behavior. The consideration is that this approach may be closer to the user experience of most .NET developers. This is also a default implementation of Avalonia:

Avalonia/src/Avalonia.Base/Platform/Storage/FileIO/BclStorageItem.cs

Lines 162 to 172 in f3df9b1

	internal static FileInfo CreateFileCore(DirectoryInfo directoryInfo, string name)
	{
	var fileName = System.IO.Path.Combine(directoryInfo.FullName, name);
	var newFile = new FileInfo(fileName);
	using var stream = newFile.Create();
	return newFile;
	}
	internal static DirectoryInfo CreateFolderCore(DirectoryInfo directoryInfo, string name) =>
	directoryInfo.CreateSubdirectory(name);

What is the current behavior?

Currently, this behavior exhibits significant inconsistencies across different operating systems:

• Android: If there is an existing document with the same display name, the provided display name might be altered to avoid conflicts.
• iOS:
• • File: If a file already exists at path, this method overwrites the contents of that file if the current process has the appropriate privileges to do so.
• • Folder: Return value: true if the directory was created, true if createIntermediates is set and the directory already exists, or false if an error occurred.Currently, createIntermediates is set to false:
    

    Avalonia/src/iOS/Avalonia.iOS/Storage/IOSStorageItem.cs

    Line 302 in d8a0008

    if (NSFileManager.DefaultManager.CreateDirectory(path, false, attributes, out var error))

• Browser:
• • File: create: true: When set to true if the file is not found, one with the specified name will be created and returned.
• Others:
• • File: Creates, or truncates and overwrites, a file in the specified path.
• • Folder: Creates all directories and subdirectories in the specified path unless they already exist. Returns: An object that represents the directory at the specified path. This object is returned regardless of whether a directory at the specified path already exists.

However, there are still a few issues that may need to be discussed to decide how to handle this. The first is whether the file should be truncated when attempting to call the CreateFileAsync method if it already exists. This question is somewhat similar to another recent PR.

Another issue is that I noticed the original code heavily used Task.FromResult and didn't put methods like CreateFile, which would cause I/O blocking, into Task.Run to avoid thread blocking. I'm not sure what the purpose of this is, or if it needs fixing. I'd be happy to improve this in another PR if needed (to avoid including too much irrelevant content in this PR).

What is the updated/expected behavior with this PR?

Now,

• in the Browser, because of { keepExistingData: false }, the file will be truncated first when attempting to write;
• in Android, these methods will first try to retrieve an existing object; if it exists, they will return it; otherwise, they will create a new one;
• in iOS, when creating a folder, if the folder already exists, you won't get an error; instead, you'll try to return the existing one.

In addition, I have reserved code to truncate existing files, but it has been commented out and we can decide whether to keep it based on the discussion.

How was the solution implemented (if it's not obvious)?

Before:

OS	Behavior if file already exists	Behavior if folder already exists
Android	Creates file (1)	Creates folder (1)
iOS	Truncates and returns file	Throws an NSErrorException
Browser	Returns file	Returns folder
Others	Truncates and returns file	Returns folder

After:

OS	Behavior if file already exists	Behavior if folder already exists
Android	Returns file	Returns folder
iOS	Truncates and returns file	Returns folder
Browser	Returns file	Returns folder
Others	Truncates and returns file	Returns folder

Checklist

• Added unit tests (if possible)?
• Added XML documentation to any related classes?
• Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

Aside from desktop environments such as Windows and Linux, the behavior of Create will change significantly on other operating systems.

Obsoletions / Deprecations

Fixed issues

Fixes #20580

[Frederisk]

I've just tried writing some basic unit tests to test these features, but I seem to be finding that there aren't any platform-specific test projects in the current solution? Or am I missing something?

[drweb86]

Thanks. File I/O is really neeeded to Avalonia to be cross-platform.

[drweb86]

For CreateFileAsync i would have it truncated content. And separate method AppendFIleAsync - that will behave like CreateFileAsync, but append on top of existing data.

That will help to have retries for fetching files. and Append - for logs.

[Frederisk]

For write actions, after #20804, when you try to call OpenWriteAsync, it will already truncate the file correctly. The question here is what happens when the Create method is called on an existing file. Just post that file; or truncate the existing file first and post it.

This can cause differences in behavior if someone tries to write some weird code:

var parentFolder = await GetParentFolderAsync();
byte[] bytes = [1, 2, 3];

// Create a file and write to it.
var file = await parentFolder.CreateFileAsync('file.txt');
var stream = await file.OpenWriteAsync();
await stream.WriteAsync(bytes);
await stream.FlushAsync();
strean.Dispose();
// Contents of file file.txt: 123

// Get and write to it.
file = await parentFolder.GetFileAsync('file.txt');
stream = await file.OpenWriteAsync();
await stream.WriteAsync(bytes);
await stream.FlushAsync();
strean.Dispose();
// Contents of file file.txt: 123

// Try creating an existing file and appending content:
file = await parentFolder.CreateFileAsync('file.txt'); // The file may or may not be truncated here, depending on the operating system.
// Contents of file file.txt: empty or 123

However, you did remind me that we do need a new method to handle file appending. AppendFileAsync seems to be confused with GetFileAsync, so perhaps IStorageFile.OpenAppendAsync or another solution would be a better choice. (Of course, that's another topic.)

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0063149-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0063217-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0063219-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]