StorageFolder.CreateFileAsync(String, CreationCollisionOption) | createFileAsync(String, CreationCollisionOption) method

Creates a new file in the current folder, and specifies what to do if a file with the same name already exists in the current folder.

Syntax

storageFolder.createFileAsync(desiredName, options).done( /* Your success and error handlers */ );

Parameters

desiredName

Type: String [JavaScript] | System.String [.NET] | Platform::String [C++]

The desired name of the file to create.

If there is an existing file in the current folder that already has the specified desiredName, the specified CreationCollisionOption determines how Windows responds to the conflict.

options

Type: CreationCollisionOption

The enum value that determines how Windows responds if the desiredName is the same as the name of an existing file in the current folder.

Return value

Type: IAsyncOperation<StorageFile>

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

Remarks

If you try to create a file in a virtual folder like a library or a file group, this method may fail.

Examples

The File Access sample shows you how to use the createFileAsync(String, CreationCollisionOption) method to create a new file in the Documents library like this:

Windows.Storage.KnownFolders.documentsLibrary.createFileAsync("sample.txt",
    Windows.Storage.CreationCollisionOption.replaceExisting).then(function (file) {
        sampleFile = file;
    });

As shown in the sample, you can use then or done to declare a function that captures and process the new file. After the createFileAsync(String, CreationCollisionOption) method completes, the new file is passed to your processing function as a StorageFile object (file in the sample).

Note  In order to create files in the Documents library, you must declare the necessary capabilities in your app manifest. Learn more about capabilities in Access to user resources using the Windows Runtime.

Requirements

See also

StorageFolder

CreateFileAsync(String)

Build date: 2/25/2013