Share via


StorageFolder.CreateFileAsync Method

Definition

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

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

Exceptions

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

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

Applies to

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

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

Exceptions

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

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

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

See also

Applies to