StorageFolder.CreateFileAsync Method

Definition

Namespace:

Windows.Storage

Overloads

CreateFileAsync(String)	Creates a new file with the specified name in the current folder.
CreateFileAsync(String, CreationCollisionOption)	Creates a new file in the current folder. This method also specifies what to do if a file with the same name already exists in the current folder.

CreateFileAsync(String)

Creates a new file with the specified name in the current folder.

public:
 virtual IAsyncOperation<StorageFile ^> ^ CreateFileAsync(Platform::String ^ desiredName) = CreateFileAsync;

/// [Windows.Foundation.Metadata.Overload("CreateFileAsyncOverloadDefaultOptions")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<StorageFile> CreateFileAsync(winrt::hstring const& desiredName);

[Windows.Foundation.Metadata.Overload("CreateFileAsyncOverloadDefaultOptions")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<StorageFile> CreateFileAsync(string desiredName);

function createFileAsync(desiredName)

Public Function CreateFileAsync (desiredName As String) As IAsyncOperation(Of StorageFile)

Parameters

desiredName

String

Platform::String

winrt::hstring

The name of the new file to create in the current folder.

Returns

IAsyncOperation<StorageFile>

When this method completes, it returns a StorageFile that represents the new file.

Implements

M:Windows.Storage.IStorageFolder.CreateFileAsync(System.String) M:Windows.Storage.IStorageFolder.CreateFileAsync(Platform::String) M:Windows.Storage.IStorageFolder.CreateFileAsync(winrt::hstring)

Attributes

OverloadAttribute RemoteAsyncAttribute

Exceptions

FileNotFoundException

The file name contains invalid characters, or the format of the filename is incorrect. Check the value of desiredName.

UnauthorizedAccessException

You don't have permission to create a file in the current folder.

Examples

The following example shows how to create a new file in the current folder by calling the CreateFileAsync (String, CreationCollisionOption) overloaded method. This example explicitly specifies a value for options that causes the operation to fail if a file with the specified desiredName already exists in the current folder.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's local folder.
StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

// Create a new file in the current folder.
// Raise an exception if the file already exists.
string desiredName = "test.txt";
StorageFile newFile = await localFolder.CreateFileAsync(desiredName, CreationCollisionOption.FailIfExists);

IAsyncAction MainPage::ExampleCoroutineAsync()
{
    // Gets the app's local folder.
    Windows::Storage::StorageFolder localFolder{ Windows::Storage::ApplicationData::Current().LocalFolder() };

    // Create a new file in the current folder, and throw an exception if the file already exists.
    std::wstring desiredName{ L"test.txt" };
    StorageFile newFile{ co_await localFolder.CreateFileAsync(desiredName, Windows::Storage::CreationCollisionOption::FailIfExists) };
    // Do something with the new file.
}

//Gets the app's local folder
StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

//Create a new file in the current folder
// Raise an exception if the file already exists
String^ desiredName = "test.txt";
auto createFileTask = create_task(localFolder->CreateFileAsync(desiredName, Windows::Storage::CreationCollisionOption::FailIfExists));
createFileTask.then([](StorageFile^ newFile)
{
  //Do something with the new file.
 });

Remarks

This method uses the FailIfExists value from the CreationCollisionOption enumeration by default. That is, this method raises an exception if a file with the same name already exists in the current folder. If you want to handle a file name collision in a different way, call the CreateFileAsync(String, CreationCollisionOption) method.

If you try to create a file in a virtual folder like a library, or a folder that represents a container for a group of files (for example, the return value from some overloads of the GetFoldersAsync method), the CreateFileAsync method may fail.

See also

• CreateFileAsync(String, CreationCollisionOption)

CreateFileAsync(String, CreationCollisionOption)

Creates a new file in the current folder. This method also specifies what to do if a file with the same name already exists in the current folder.

public:
 virtual IAsyncOperation<StorageFile ^> ^ CreateFileAsync(Platform::String ^ desiredName, CreationCollisionOption options) = CreateFileAsync;

/// [Windows.Foundation.Metadata.Overload("CreateFileAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<StorageFile> CreateFileAsync(winrt::hstring const& desiredName, CreationCollisionOption const& options);

[Windows.Foundation.Metadata.Overload("CreateFileAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<StorageFile> CreateFileAsync(string desiredName, CreationCollisionOption options);

function createFileAsync(desiredName, options)

Public Function CreateFileAsync (desiredName As String, options As CreationCollisionOption) As IAsyncOperation(Of StorageFile)

Parameters

desiredName

String

Platform::String

winrt::hstring

The name of the new file to create in the current folder.

options

CreationCollisionOption

One of the enumeration values that determines how to handle the collision if a file with the specified desiredName already exists in the current folder.

Returns

IAsyncOperation<StorageFile>

When this method completes, it returns a StorageFile that represents the new file.

Implements

M:Windows.Storage.IStorageFolder.CreateFileAsync(System.String,Windows.Storage.CreationCollisionOption) M:Windows.Storage.IStorageFolder.CreateFileAsync(Platform::String,Windows.Storage.CreationCollisionOption) M:Windows.Storage.IStorageFolder.CreateFileAsync(winrt::hstring,Windows.Storage.CreationCollisionOption)

Attributes

OverloadAttribute RemoteAsyncAttribute

Exceptions

Exception

You specified CreationCollisionOption.FailIfExists and a file with the specified desiredName already exists in the current folder.

FileNotFoundException

The format of the filename is incorrect. Check the value of desiredName.

UnauthorizedAccessException

You don't have permission to create a file in the current folder.

See also

• CreateFileAsync(String)