StorageFile StorageFile StorageFile StorageFile Class

Definition

Represents a file. Provides information about the file and its content, and ways to manipulate them.

public sealed class StorageFilepublic sealed class StorageFilePublic NotInheritable Class StorageFilepublic sealed class StorageFile
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Typically, you access StorageFile objects as the result of asynchronous method and/or function calls. For example, both of the static methods GetFileFromPathAsync(String) and GetFileFromApplicationUriAsync(Uri) return a StorageFile that represents the specified file.

Additionally, whenever you call a file picker to let the user pick a file (or files) the file picker will return the file as a StorageFile.

Note

StorageFile objects can't represent files that are ".lnk", ".url", or ".wsh" file types.

Examples

This example shows you how to call a file picker, using PickSingleFileAsync() to capture and process a file that the users picks.

StorageFile file = await openPicker.PickSingleFileAsync();
// Process picked file
if (file != null)
{
    // Store file for future access
    fileToken = Windows.Storage.AccessCache.StorageApplicationPermissions.FutureAccessList.Add(file);
}
else
{
    // The user didn't pick a file
}

openPicker.pickSingleFileAsync().then(function (file) {
   if (file) {
       // Process picked file

       // Store file for future access
       var fileToken = Windows.Storage.AccessCache.StorageApplicationPermissions.futureAccessList.add(file);
   } else {
       // The user didn't pick a file
   }
});

After PickSingleFileAsync() completes, file gets the picked file as a StorageFile.

In the example, openPicker contains a FileOpenPicker object. To learn more about using file picker see Open files and folders with a picker.

Additionally, fileToken gets an identifier that you can use to retrieve the file from the FutureAccessList. To learn more about storing files and folders so you can access them again later, see FutureAccessList, MostRecentlyUsedList and How to track recently used files and folders.

Properties

Attributes Attributes Attributes Attributes

Gets the attributes of a file.

public FileAttributes Attributes { get; }public FileAttributes Attributes { get; }Public ReadOnly Property Attributes As FileAttributespublic FileAttributes Attributes { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

ContentType ContentType ContentType ContentType

Gets the MIME type of the contents of the file.

public string ContentType { get; }public string ContentType { get; }Public ReadOnly Property ContentType As stringpublic string ContentType { get; }
Value
string string string string

The MIME type of the file contents.

For example, a music file might have the "audio/mpeg" MIME type.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

DateCreated DateCreated DateCreated DateCreated

Gets the date and time when the current file was created.

public DateTime DateCreated { get; }public DateTimeOffset DateCreated { get; }Public ReadOnly Property DateCreated As DateTimeOffsetpublic DateTime DateCreated { get; }
Value
DateTime DateTime DateTime DateTime

The date and time when the current file was created.

For example, in string format the DateTime that a file was created might be "Fri Sep 16 13:47:08 PDT 2016".

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

If the date property isn't set, this value defaults to 0 which can be translated into misleading dates in different programming languages. In JavaScript, for example, 0 translates to December 16, 1600. You should always check that this property is a real value and not 0.

DisplayName DisplayName DisplayName DisplayName

Gets a user-friendly name for the file.

public string DisplayName { get; }public string DisplayName { get; }Public ReadOnly Property DisplayName As stringpublic string DisplayName { get; }
Value
string string string string

The user-friendly name for the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

DisplayType DisplayType DisplayType DisplayType

Gets a user-friendly description of the type of the file.

public string DisplayType { get; }public string DisplayType { get; }Public ReadOnly Property DisplayType As stringpublic string DisplayType { get; }
Value
string string string string

The user-friendly description of the type of the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

For example, an image file might have a user-friendly type of "JPG File".

FileType FileType FileType FileType

Gets the type (file name extension) of the file.

public string FileType { get; }public string FileType { get; }Public ReadOnly Property FileType As stringpublic string FileType { get; }
Value
string string string string

The file name extension of the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

For example, an image file might have the ".jpg" file type.

FolderRelativeId FolderRelativeId FolderRelativeId FolderRelativeId

Gets an identifier for the file. This ID is unique for the query result or StorageFolder that contains the file and can be used to distinguish between items that have the same name.

public string FolderRelativeId { get; }public string FolderRelativeId { get; }Public ReadOnly Property FolderRelativeId As stringpublic string FolderRelativeId { get; }
Value
string string string string

The identifier for the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

You create a query result object when you create a query using one of the methods on a StorageFolder object. Depending on the method you call, your query result object could be a StorageFileQueryResult, a StorageFolderQueryResult, or a StorageItemQueryResult object.

IsAvailable IsAvailable IsAvailable IsAvailable

Indicates if the file is local, is cached locally, or can be downloaded.

public bool IsAvailable { get; }public bool IsAvailable { get; }Public ReadOnly Property IsAvailable As boolpublic bool IsAvailable { get; }
Value
bool bool bool bool

True if the file is local, is cached locally, or can be downloaded. Otherwise, false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Name Name Name Name

Gets the name of the file including the file name extension.

public string Name { get; }public string Name { get; }Public ReadOnly Property Name As stringpublic string Name { get; }
Value
string string string string

The name of the file including the file name extension.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Path Path Path Path

Gets the full file-system path of the current file, if the file has a path.

public string Path { get; }public string Path { get; }Public ReadOnly Property Path As stringpublic string Path { get; }
Value
string string string string

The full path of the file, if the file has a path in the user's file-system.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Do not rely on this property to access a file because some files may not have file-system paths. For example if the file is backed by a URI, or was picked using the file picker, the file is not guaranteed to have a file-system path.

Properties Properties Properties Properties

Gets an object that provides access to the content-related properties of the file.

public StorageItemContentProperties Properties { get; }public StorageItemContentProperties Properties { get; }Public ReadOnly Property Properties As StorageItemContentPropertiespublic StorageItemContentProperties Properties { get; }
Value
StorageItemContentProperties StorageItemContentProperties StorageItemContentProperties StorageItemContentProperties

The object that provides access to the content-related properties of the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Note

Properties that are get or set using a property handler that is defined by another app (like Microsoft Word) may not be accessible. Instead, you can try to get these properties using a file query that is backed by the system index. For more information, see QueryOptions.

For more code samples about accessing properties, see the File access sample.

Examples

This example demonstrates how to retrieve content properties or specified properties from a file using Properties.

try
{
    StorageFile file = rootPage.sampleFile;
       if (file != null)
       {
        StringBuilder outputText = new StringBuilder();

           // Get image properties
              ImageProperties imageProperties = await file.Properties.GetImagePropertiesAsync();
              outputText.AppendLine("Date taken: " + imageProperties.DateTaken);
              outputText.AppendLine("Rating: " + imageProperties.Rating);

              // Specify more properties to retrieve
        readonly string dateAccessedProperty = "System.DateAccessed";
        readonly string fileOwnerProperty = "System.FileOwner";
              List<string> propertiesName = new List<string>();
              propertiesName.Add(dateAccessedProperty);
              propertiesName.Add(fileOwnerProperty);

        // Get the specified properties through StorageFile.Properties
              IDictionary<string, object> extraProperties = await file.Properties.RetrievePropertiesAsync(propertiesName);
              var propValue = extraProperties[dateAccessedProperty];
              if (propValue != null)
              {
                     outputText.AppendLine("Date accessed: " + propValue);
              }
              propValue = extraProperties[fileOwnerProperty];
              if (propValue != null)
              {
                     outputText.AppendLine("File owner: " + propValue);
              }
       }
}
// Handle errors with catch blocks
catch (FileNotFoundException)
{
    // For example, handle a file not found error
}

var file = SdkSample.sampleFile;
if (file !== null) {
    var outputDiv = document.getElementById("output");

    // Get image properties
    file.properties.getImagePropertiesAsync().then(function (imageProperties) {
        outputDiv.innerHTML += "Date taken: " + imageProperties.dateTaken + "<br />";
        outputDiv.innerHTML += "Rating: " + imageProperties.rating + "<br />";

        // Specify more properties to retrieve
        var dateAccessedProperty = "System.DateAccessed";
        var fileOwnerProperty    = "System.FileOwner";

        // Get the specified properties through storageFile.properties
        return file.properties.retrievePropertiesAsync([fileOwnerProperty, dateAccessedProperty]);
    }).done(function (extraProperties) {
        var propValue = extraProperties[dateAccessedProperty];
        if (propValue !== null) {
            outputDiv.innerHTML += "Date accessed: " + propValue + "<br />";
        }
        propValue = extraProperties[fileOwnerProperty];
        if (propValue !== null) {
            outputDiv.innerHTML += "File owner: " + propValue;
        }
    },
    // Handle errors with an error function
       function (error) {
           // Handle errors encountered while retrieving properties
    });
}

After GetImagePropertiesAsync() completes, imageProperties gets a ImageProperties object. Additionally, after RetrievePropertiesAsync(IIterable<String>) completes, extraProperties gets an object that contains the specified properties.

In the example, file contains a StorageFile that represents the file to retrieve properties for.

Provider Provider Provider Provider

Gets the StorageProvider object that contains info about the service that stores the current file.

public StorageProvider Provider { get; }public StorageProvider Provider { get; }Public ReadOnly Property Provider As StorageProviderpublic StorageProvider Provider { get; }
Value
StorageProvider StorageProvider StorageProvider StorageProvider

The StorageProvider object that contains info about the service that stores the current file. The file may be stored by the local file system or by a remote service like Microsoft OneDrive.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Methods

CopyAndReplaceAsync(IStorageFile) CopyAndReplaceAsync(IStorageFile) CopyAndReplaceAsync(IStorageFile) CopyAndReplaceAsync(IStorageFile)

Replaces the specified file with a copy of the current file.

public IAsyncAction CopyAndReplaceAsync(IStorageFile fileToReplace)public IAsyncAction CopyAndReplaceAsync(IStorageFile fileToReplace)Public Function CopyAndReplaceAsync(fileToReplace As IStorageFile) As IAsyncActionpublic IAsyncAction CopyAndReplaceAsync(IStorageFile fileToReplace)
Parameters
fileToReplace
IStorageFile IStorageFile IStorageFile IStorageFile

The file to replace.

Returns

No object or value is returned when this method completes.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

CopyAsync(IStorageFolder) CopyAsync(IStorageFolder) CopyAsync(IStorageFolder) CopyAsync(IStorageFolder)

Creates a copy of the file in the specified folder.

public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder)public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder)Public Function CopyAsync(destinationFolder As IStorageFolder) As IAsyncOperation( Of StorageFile )public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the copy of the file is created.

Returns

When this method completes, it returns a StorageFile that represents the copy of the file created in the destinationFolder.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

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 destination folder. If you want to handle a file name collision in a different way, call the CopyAsync(IStorageFolder, String, NameCollisionOption) overloaded method.

Examples

The following example copies a file to the specified folder and renames the copy by calling the CopyAsync(IStorageFolder, String, NameCollisionOption) method. This example explicitly specifies a value for option that replaces the file in the destination folder if a file with the specified name already exists.

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

// Get the app's temporary folder.
StorageFolder tempFolder = ApplicationData.Current.TemporaryFolder;

// Create a sample file in the temporary folder.
string newFileName = "test.txt";
StorageFile newFile = await tempFolder.CreateFileAsync(newFileName);

// Get the app's local folder to use as the destination folder.
StorageFolder localFolder = ApplicationData.Current.LocalFolder;

// Specify a new name for the copied file.
string renamedFileName = "renamed_test.txt";

// Copy the file to the destination folder and rename it.
// Replace the existing file if the file already exists.
StorageFile copiedFile = await newFile.CopyAsync(localFolder, renamedFileName, NameCollisionOption.ReplaceExisting);
// Get the app's temporary folder.
var ApplicationData = Windows.Storage.ApplicationData;
var tempFolder = ApplicationData.current.temporaryFolder;

// Create a sample file in the temporary folder.
var newFileName = "test.txt";
var newFilePromise = tempFolder.createFileAsync(newFileName);
var copiedFilePromise = newFilePromise.then(function (newFile) 
{
    // Get the app's local folder to use as the destination folder.
    var localFolder = ApplicationData.current.localFolder;

    // Specify a new name for the copied file.
    var renamedFileName = "renamed_test.txt";

    // Copy the file to the destination folder and rename it.
    // Replace the existing file if the file already exists.
    var NameCollisionOption = Windows.Storage.NameCollisionOption;
    return newFile.copyAsync(localFolder, renamedFileName, NameCollisionOption.replaceExisting);
});
copiedFilePromise.done(function copySuccess(copiedFile) 
{
    // File was copied to the destination folder.
}, function copyFail(failure) 
{
    // File creation or copy failed.
});
 //Get the app's temporary folder
 StorageFolder^ sourceFolder = ApplicationData::Current->TemporaryFolder;
 StorageFolder^ targetFolder = ApplicationData::Current->LocalFolder;

 // Choose source file name and new name for the copied file
 String^ newFileName = "test.txt";
 String^ copyFileName = "renamed_test.txt";

 //Create a sample file in the temporary folder
 auto copyFileTask = create_task(sourceFolder->CreateFileAsync(newFileName, Windows::Storage::CreationCollisionOption::ReplaceExisting)).then
  ([targetFolder, copyFileName](StorageFile^ sourceFile) -> task<StorageFile^>
 {
  //Overwrite any exisitng file with the same name 
  auto copyFileTask = sourceFile->CopyAsync(targetFolder,copyFileName,Windows::Storage::NameCollisionOption::ReplaceExisting);
  return create_task(copyFileTask);
 }).then([](StorageFile^ copiedFile){
  //do something with copied file
 });

CopyAsync(IStorageFolder, String) CopyAsync(IStorageFolder, String) CopyAsync(IStorageFolder, String) CopyAsync(IStorageFolder, String)

Creates a copy of the file in the specified folder and renames the copy.

public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName)public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName)Public Function CopyAsync(destinationFolder As IStorageFolder, desiredNewName As String) As IAsyncOperation( Of StorageFile )public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the copy of the file is created.

desiredNewName
System.String System.String System.String System.String

The new name for the copy of the file created in the destinationFolder.

Returns

When this method completes, it returns a StorageFile that represents the copy of the file created in the destinationFolder.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

CopyAsync(IStorageFolder, String, NameCollisionOption) CopyAsync(IStorageFolder, String, NameCollisionOption) CopyAsync(IStorageFolder, String, NameCollisionOption) CopyAsync(IStorageFolder, String, NameCollisionOption)

Creates a copy of the file in the specified folder and renames the copy. This method also specifies what to do if a file with the same name already exists in the destination folder.

public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)Public Function CopyAsync(destinationFolder As IStorageFolder, desiredNewName As String, option As NameCollisionOption) As IAsyncOperation( Of StorageFile )public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the copy of the file is created.

desiredNewName
System.String System.String System.String System.String

The new name for the copy of the file created in the destinationFolder.

option
NameCollisionOption NameCollisionOption NameCollisionOption NameCollisionOption

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

Returns

When this method completes, it returns a StorageFile that represents the copy of the file created in the destinationFolder.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

CreateStreamedFileAsync(String, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) CreateStreamedFileAsync(String, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) CreateStreamedFileAsync(String, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) CreateStreamedFileAsync(String, StreamedFileDataRequestedHandler, IRandomAccessStreamReference)

Creates a StorageFile to represent the specified stream of data. This method lets the app produce the data on-demand by specifying a function to be invoked when the StorageFile that represents the stream is first accessed.

public static IAsyncOperation<StorageFile> CreateStreamedFileAsync(String displayNameWithExtension, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)public static IAsyncOperation<StorageFile> CreateStreamedFileAsync(String displayNameWithExtension, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)Public Static Function CreateStreamedFileAsync(displayNameWithExtension As String, dataRequested As StreamedFileDataRequestedHandler, thumbnail As IRandomAccessStreamReference) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> CreateStreamedFileAsync(String displayNameWithExtension, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)
Parameters
displayNameWithExtension
System.String System.String System.String System.String

The user-friendly name of the StorageFile to create, including a file type extension.

dataRequested
StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler

The function that should be invoked when the StorageFile that is returned is first accessed. This function should produce the data stream represented by the returned StorageFile and lets the app produce data on-demand instead of writing the contents of the file at creation time.

thumbnail
IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference

The thumbnail image for the StorageFile to create.

For a high-quality thumbnail, one edge of this thumbnail should be at least 1024 pixels.

Returns

When this method completes, it returns a StorageFile object that represents the new stream of data.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Both this method and CreateStreamedFileFromUriAsync(String, Uri, IRandomAccessStreamReference) can be used to create a StorageFile that can be passed to other methods or passed to another app through app contracts.

These methods let you defer expensive operations to produce the data until that data needed (when it is first accessed). This avoids creating unnecessary delays in user interaction while the data is produced.

CreateStreamedFileFromUriAsync(String, Uri, IRandomAccessStreamReference) CreateStreamedFileFromUriAsync(String, Uri, IRandomAccessStreamReference) CreateStreamedFileFromUriAsync(String, Uri, IRandomAccessStreamReference) CreateStreamedFileFromUriAsync(String, Uri, IRandomAccessStreamReference)

Creates a StorageFile to represent a stream of data from the specified Uniform Resource Identifier (URI) resource. This method lets the app download the data on-demand when the StorageFile that represents the stream is first accessed.

public static IAsyncOperation<StorageFile> CreateStreamedFileFromUriAsync(String displayNameWithExtension, Uri uri, IRandomAccessStreamReference thumbnail)public static IAsyncOperation<StorageFile> CreateStreamedFileFromUriAsync(String displayNameWithExtension, Uri uri, IRandomAccessStreamReference thumbnail)Public Static Function CreateStreamedFileFromUriAsync(displayNameWithExtension As String, uri As Uri, thumbnail As IRandomAccessStreamReference) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> CreateStreamedFileFromUriAsync(String displayNameWithExtension, Uri uri, IRandomAccessStreamReference thumbnail)
Parameters
displayNameWithExtension
System.String System.String System.String System.String

The user-friendly name of the StorageFile to create, including a file type extension.

uri
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the resource used to create the StorageFile.

thumbnail
IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference

The thumbnail image for the StorageFile to create.

For a high-quality thumbnail, one edge of this thumbnail should be at least 1024 pixels.

Returns

When this method completes, it returns a StorageFile object that represents the Uniform Resource Identifier (URI) resource.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

This method is nearly equivalent to CreateStreamedFileAsync(String, StreamedFileDataRequestedHandler, IRandomAccessStreamReference), except when using this method, the system provides a StreamedFileDataRequestedHandler on the app's behalf and implements this function to download the specified Uri into the streamed file.

DeleteAsync() DeleteAsync() DeleteAsync() DeleteAsync()

Deletes the current file.

public IAsyncAction DeleteAsync()public IAsyncAction DeleteAsync()Public Function DeleteAsync() As IAsyncActionpublic IAsyncAction DeleteAsync()
Returns

No object or value is returned by this method when it completes.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

This method uses StorageDeleteOption to determine whether the item is deleted permanently.

FileNotFoundException is thrown if the file does not exist..

DeleteAsync(StorageDeleteOption) DeleteAsync(StorageDeleteOption) DeleteAsync(StorageDeleteOption) DeleteAsync(StorageDeleteOption)

Deletes the current file, optionally deleting the item permanently.

public IAsyncAction DeleteAsync(StorageDeleteOption option)public IAsyncAction DeleteAsync(StorageDeleteOption option)Public Function DeleteAsync(option As StorageDeleteOption) As IAsyncActionpublic IAsyncAction DeleteAsync(StorageDeleteOption option)
Parameters
option
StorageDeleteOption StorageDeleteOption StorageDeleteOption StorageDeleteOption

A value that indicates whether to delete the item permanently.

Returns

No object or value is returned by this method when it completes.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetBasicPropertiesAsync() GetBasicPropertiesAsync() GetBasicPropertiesAsync() GetBasicPropertiesAsync()

Gets the basic properties of the current file.

public IAsyncOperation<BasicProperties> GetBasicPropertiesAsync()public IAsyncOperation<BasicProperties> GetBasicPropertiesAsync()Public Function GetBasicPropertiesAsync() As IAsyncOperation( Of BasicProperties )public IAsyncOperation<BasicProperties> GetBasicPropertiesAsync()
Returns

When this method completes successfully, it returns the basic properties of the current file as a BasicProperties object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

This method will return E_ILLEGAL_METHOD_CALL if there are other async operations in progress on the same StorageItem instance. Make sure that another thread isn't modifying the StorageItem at the same time.

Examples

This example shows you how to access basic properties of a file using the GetBasicPropertiesAsync() method.

storageFile.getBasicPropertiesAsync().then(
    function (basicProperties) {
        var size  = basicProperties.size;
    }
);

You must have a StorageFile object (storageFile in the example) that represents your file in order to use the GetBasicPropertiesAsync() method.

GetFileFromApplicationUriAsync(Uri) GetFileFromApplicationUriAsync(Uri) GetFileFromApplicationUriAsync(Uri) GetFileFromApplicationUriAsync(Uri)

Gets a StorageFile object to represent the specified Uniform Resource Identifier (URI) app resource. For examples of sample URIs see How to load file resources.

public static IAsyncOperation<StorageFile> GetFileFromApplicationUriAsync(Uri uri)public static IAsyncOperation<StorageFile> GetFileFromApplicationUriAsync(Uri uri)Public Static Function GetFileFromApplicationUriAsync(uri As Uri) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> GetFileFromApplicationUriAsync(Uri uri)
Parameters
uri
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the app resource to get a StorageFile to represent.

Returns

When this method completes, it returns a StorageFile object that represents the Uniform Resource Identifier (URI) resource.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

You can use this method to access your app's resources using either "ms-appx://" or "ms-appdata://" Uniform Resource Identifier (URI).

Examples

var uri = new Windows.Foundation.Uri("ms-appx:///datafile.xml")
Windows.Storage.StorageFile.getFileFromApplicationUriAsync(uri).done( /* Your success and error handlers */ );

GetFileFromPathAsync(String) GetFileFromPathAsync(String) GetFileFromPathAsync(String) GetFileFromPathAsync(String)

Gets a StorageFile object to represent the file at the specified path.

public static IAsyncOperation<StorageFile> GetFileFromPathAsync(String path)public static IAsyncOperation<StorageFile> GetFileFromPathAsync(String path)Public Static Function GetFileFromPathAsync(path As String) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> GetFileFromPathAsync(String path)
Parameters
path
System.String System.String System.String System.String

The path of the file to get a StorageFile to represent.

If your path uses slashes, make sure you use backslashes (). Forward slashes (/) are not accepted by this method.

Returns

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

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetParentAsync() GetParentAsync() GetParentAsync() GetParentAsync()

Gets the parent folder of the current file.

public IAsyncOperation<StorageFolder> GetParentAsync()public IAsyncOperation<StorageFolder> GetParentAsync()Public Function GetParentAsync() As IAsyncOperation( Of StorageFolder )public IAsyncOperation<StorageFolder> GetParentAsync()
Returns

When this method completes, it returns the parent folder as a StorageFolder.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetScaledImageAsThumbnailAsync(ThumbnailMode) GetScaledImageAsThumbnailAsync(ThumbnailMode) GetScaledImageAsThumbnailAsync(ThumbnailMode) GetScaledImageAsThumbnailAsync(ThumbnailMode)

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail.

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the item.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32)

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail and the requested size.

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

requestedSize
System.UInt32 System.UInt32 System.UInt32 System.UInt32

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the item.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetScaledImageAsThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions)

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail, the requested size, and the specified options

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32, options As ThumbnailOptions) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

requestedSize
System.UInt32 System.UInt32 System.UInt32 System.UInt32

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

options
ThumbnailOptions ThumbnailOptions ThumbnailOptions ThumbnailOptions

The enum value that describes the desired behavior to use to retrieve the thumbnail image. The specified behavior might affect the size and/or quality of the image and how quickly the thumbnail image is retrieved.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the item.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetThumbnailAsync(ThumbnailMode) GetThumbnailAsync(ThumbnailMode) GetThumbnailAsync(ThumbnailMode) GetThumbnailAsync(ThumbnailMode)

Retrieves an adjusted thumbnail image for the file, determined by the purpose of the thumbnail.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode)Public Function GetThumbnailAsync(mode As ThumbnailMode) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

In Windows Phone Store app, the GetThumbnailAsync(ThumbnailMode, UInt32) method returns the default icon for a music file instead of the expected icon. This happens when you call the GetThumbnailAsync(ThumbnailMode, UInt32) method with a ThumbnailMode value of MusicView.

GetThumbnailAsync(ThumbnailMode, UInt32) GetThumbnailAsync(ThumbnailMode, UInt32) GetThumbnailAsync(ThumbnailMode, UInt32) GetThumbnailAsync(ThumbnailMode, UInt32)

Retrieves an adjusted thumbnail image for the file, determined by the purpose of the thumbnail and the requested size.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)Public Function GetThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

requestedSize
System.UInt32 System.UInt32 System.UInt32 System.UInt32

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

GetThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) GetThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions)

Retrieves an adjusted thumbnail image for the file, determined by the purpose of the thumbnail, the requested size, and the specified options.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)Public Function GetThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32, options As ThumbnailOptions) As IAsyncOperation( Of StorageItemThumbnail )public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enum value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

requestedSize
System.UInt32 System.UInt32 System.UInt32 System.UInt32

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

options
ThumbnailOptions ThumbnailOptions ThumbnailOptions ThumbnailOptions

The enum value that describes the desired behavior to use to retrieve the thumbnail image. The specified behavior might affect the size and/or quality of the image and how quickly the thumbnail image is retrieved.

Returns

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image or null if there is no thumbnail image associated with the file.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Examples

This example shows you how to capture the thumbnail of a file using the GetThumbnailAsync(ThumbnailMode, UInt32, ThumbnailOptions) method.

storageFile.getThumbnailAsync(
    Windows.Storage.FileProperties.ThumbnailMode.musicView,
    100,
    Windows.Storage.FileProperties.ThumbnailOptions.useCurrentScale).then(
        function (storageItemThumbnail) {
            // Add code to process thumbnail
        }
    );

You must have a StorageFile object (storageFile in the example) that represents your file in order to use one of the GetThumbnailAsync(ThumbnailMode, UInt32) methods.

IsEqual(IStorageItem) IsEqual(IStorageItem) IsEqual(IStorageItem) IsEqual(IStorageItem)

Indicates whether the current file is equal to the specified file.

public bool IsEqual(IStorageItem item)public bool IsEqual(IStorageItem item)Public Function IsEqual(item As IStorageItem) As boolpublic bool IsEqual(IStorageItem item)
Parameters
item
IStorageItem IStorageItem IStorageItem IStorageItem

The IStorageItem object that represents a file to compare against.

Returns
bool bool bool bool

Returns true if the current file is equal to the specified file; otherwise false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

Use the IsEqual(IStorageItem) method to determine whether two storage items represent the same file or folder.

This method compares the Path property of both items to determine if they are the same. If there is no Path (if the item is a library for example), or if the paths do not match the items are compared using IShellItem::Compare.

This example shows how to compare two storage files for equality.

function openNewFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker;
    picker.fileTypeFilter.replaceAll(["*"]);
    picker.pickSingleFileAsync().then(function (file) {
        var alreadyOpenedFile = null;
        _openFiles.some(function (openFile) {
            if (file.IsEqual(openFile.file)) {
                alreadyOpenedFile = openFile;
                return true;
            }
            return false;
        });

        if (alreadyOpenedFile != null) {
            alreadyOpenedFile.window.activate();
        } else {
            createNewFileViewerWindow(file);
        }
    });
}

IsOfType(StorageItemTypes) IsOfType(StorageItemTypes) IsOfType(StorageItemTypes) IsOfType(StorageItemTypes)

Determines whether the current StorageFile matches the specified StorageItemTypes value.

public bool IsOfType(StorageItemTypes type)public bool IsOfType(StorageItemTypes type)Public Function IsOfType(type As StorageItemTypes) As boolpublic bool IsOfType(StorageItemTypes type)
Parameters
Returns
bool bool bool bool

True if the StorageFile matches the specified value; otherwise false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

MoveAndReplaceAsync(IStorageFile) MoveAndReplaceAsync(IStorageFile) MoveAndReplaceAsync(IStorageFile) MoveAndReplaceAsync(IStorageFile)

Moves the current file to the location of the specified file and replaces the specified file in that location.

public IAsyncAction MoveAndReplaceAsync(IStorageFile fileToReplace)public IAsyncAction MoveAndReplaceAsync(IStorageFile fileToReplace)Public Function MoveAndReplaceAsync(fileToReplace As IStorageFile) As IAsyncActionpublic IAsyncAction MoveAndReplaceAsync(IStorageFile fileToReplace)
Parameters
fileToReplace
IStorageFile IStorageFile IStorageFile IStorageFile

The file to replace.

Returns

No object or value is returned by this method.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

MoveAsync(IStorageFolder) MoveAsync(IStorageFolder) MoveAsync(IStorageFolder) MoveAsync(IStorageFolder)

Moves the current file to the specified folder.

public IAsyncAction MoveAsync(IStorageFolder destinationFolder)public IAsyncAction MoveAsync(IStorageFolder destinationFolder)Public Function MoveAsync(destinationFolder As IStorageFolder) As IAsyncActionpublic IAsyncAction MoveAsync(IStorageFolder destinationFolder)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the file is moved.

This destination folder must be a physical location. Otherwise, if the destination folder exists only in memory, like a file group, this method fails and throws an exception.

Returns

No object or value is returned by this method.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

MoveAsync(IStorageFolder, String) MoveAsync(IStorageFolder, String) MoveAsync(IStorageFolder, String) MoveAsync(IStorageFolder, String)

Moves the current file to the specified folder and renames the file according to the desired name.

public IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName)public IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName)Public Function MoveAsync(destinationFolder As IStorageFolder, desiredNewName As String) As IAsyncActionpublic IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the file is moved.

This destination folder must be a physical location. Otherwise, if the destination folder exists only in memory, like a file group, this method fails and throws an exception.

desiredNewName
System.String System.String System.String System.String

The desired name of the file after it is moved.

If there is an existing file in the destination folder that already has the specified desiredNewName, Windows generates a unique name for the file.

Returns

No object or value is returned by this method.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

MoveAsync(IStorageFolder, String, NameCollisionOption) MoveAsync(IStorageFolder, String, NameCollisionOption) MoveAsync(IStorageFolder, String, NameCollisionOption) MoveAsync(IStorageFolder, String, NameCollisionOption)

Moves the current file to the specified folder and renames the file according to the desired name. This method also specifies what to do if a file with the same name already exists in the specified folder.

public IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)public IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)Public Function MoveAsync(destinationFolder As IStorageFolder, desiredNewName As String, option As NameCollisionOption) As IAsyncActionpublic IAsyncAction MoveAsync(IStorageFolder destinationFolder, String desiredNewName, NameCollisionOption option)
Parameters
destinationFolder
IStorageFolder IStorageFolder IStorageFolder IStorageFolder

The destination folder where the file is moved.

This destination folder must be a physical location. Otherwise, if the destination folder exists only in memory, like a file group, this method fails and throws an exception.

desiredNewName
System.String System.String System.String System.String

The desired name of the file after it is moved.

If there is an existing file in the destination folder that already has the specified desiredNewName, the specified NameCollisionOption determines how Windows responds to the conflict.

option
NameCollisionOption NameCollisionOption NameCollisionOption NameCollisionOption

An enum value that determines how Windows responds if the desiredNewName is the same as the name of an existing file in the destination folder.

Returns

No object or value is returned by this method.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenAsync(FileAccessMode) OpenAsync(FileAccessMode) OpenAsync(FileAccessMode) OpenAsync(FileAccessMode)

Opens a random-access stream with the specified options over the specified file.

public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode)public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode)Public Function OpenAsync(accessMode As FileAccessMode) As IAsyncOperation( Of IRandomAccessStream )public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode)
Parameters
accessMode
FileAccessMode FileAccessMode FileAccessMode FileAccessMode

One of the enumeration values that specifies the type of access to allow.

Returns

When this method completes, it returns an IRandomAccessStream that contains the requested random-access stream.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenAsync(FileAccessMode, StorageOpenOptions) OpenAsync(FileAccessMode, StorageOpenOptions) OpenAsync(FileAccessMode, StorageOpenOptions) OpenAsync(FileAccessMode, StorageOpenOptions)

Opens a random-access stream with the specified options over the specified file.

public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode, StorageOpenOptions options)public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode, StorageOpenOptions options)Public Function OpenAsync(accessMode As FileAccessMode, options As StorageOpenOptions) As IAsyncOperation( Of IRandomAccessStream )public IAsyncOperation<IRandomAccessStream> OpenAsync(FileAccessMode accessMode, StorageOpenOptions options)
Parameters
accessMode
FileAccessMode FileAccessMode FileAccessMode FileAccessMode

One of the enumeration values that specifies the type of access to allow.

options
StorageOpenOptions StorageOpenOptions StorageOpenOptions StorageOpenOptions

A bitwise combination of the enumeration values that specify options for opening the stream.

Returns

When this method completes, it returns an IRandomAccessStream that contains the requested random-access stream.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenReadAsync() OpenReadAsync() OpenReadAsync() OpenReadAsync()

Opens a random-access stream over the current file for reading file contents.

public IAsyncOperation<IRandomAccessStreamWithContentType> OpenReadAsync()public IAsyncOperation<IRandomAccessStreamWithContentType> OpenReadAsync()Public Function OpenReadAsync() As IAsyncOperation( Of IRandomAccessStreamWithContentType )public IAsyncOperation<IRandomAccessStreamWithContentType> OpenReadAsync()
Returns

When this method completes, it returns the random-access stream (type IRandomAccessStreamWithContentType ).

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenSequentialReadAsync() OpenSequentialReadAsync() OpenSequentialReadAsync() OpenSequentialReadAsync()

Opens a sequential-access stream over the current file for reading file contents.

public IAsyncOperation<IInputStream> OpenSequentialReadAsync()public IAsyncOperation<IInputStream> OpenSequentialReadAsync()Public Function OpenSequentialReadAsync() As IAsyncOperation( Of IInputStream )public IAsyncOperation<IInputStream> OpenSequentialReadAsync()
Returns

When this method completes, it returns the sequential-access stream (type IInputStream ).

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenTransactedWriteAsync() OpenTransactedWriteAsync() OpenTransactedWriteAsync() OpenTransactedWriteAsync()

Opens a random-access stream to the file that can be used for transacted-write operations.

public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync()public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync()Public Function OpenTransactedWriteAsync() As IAsyncOperation( Of StorageStreamTransaction )public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync()
Returns

When this method completes, it returns a StorageStreamTransaction that contains the random-access stream and methods that can be used to complete transactions.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

OpenTransactedWriteAsync(StorageOpenOptions) OpenTransactedWriteAsync(StorageOpenOptions) OpenTransactedWriteAsync(StorageOpenOptions) OpenTransactedWriteAsync(StorageOpenOptions)

Opens a random-access stream to the file that can be used for transacted-write operations with the specified options.

public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync(StorageOpenOptions options)public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync(StorageOpenOptions options)Public Function OpenTransactedWriteAsync(options As StorageOpenOptions) As IAsyncOperation( Of StorageStreamTransaction )public IAsyncOperation<StorageStreamTransaction> OpenTransactedWriteAsync(StorageOpenOptions options)
Parameters
options
StorageOpenOptions StorageOpenOptions StorageOpenOptions StorageOpenOptions

A bitwise combination of the enumeration values that specify options for opening the stream.

Returns

When this method completes, it returns a StorageStreamTransaction that contains the random-access stream and methods that can be used to complete transactions.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

RenameAsync(String) RenameAsync(String) RenameAsync(String) RenameAsync(String)

Renames the current file.

public IAsyncAction RenameAsync(String desiredName)public IAsyncAction RenameAsync(String desiredName)Public Function RenameAsync(desiredName As String) As IAsyncActionpublic IAsyncAction RenameAsync(String desiredName)
Parameters
desiredName
System.String System.String System.String System.String

The desired, new name of the current item.

Returns

No object or value is returned by this method when it completes.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

If the name you specify is invalid, this method throws an exception. To handle all the ways the specified name could be invalid, you must catch all four of these exceptions:

E_INVALIDARG
E_FAIL
ERROR_FILENAME_EXCED_RANGE
ERROR_INVALID_NAME

If the file is deleted before the rename finishes, this method throws the ERROR_FILE_NOT_FOUND exception. You must also catch and handle this exception when you use this method.

RenameAsync(String, NameCollisionOption) RenameAsync(String, NameCollisionOption) RenameAsync(String, NameCollisionOption) RenameAsync(String, NameCollisionOption)

Renames the current file. This method also specifies what to do if an existing item in the current file's location has the same name.

public IAsyncAction RenameAsync(String desiredName, NameCollisionOption option)public IAsyncAction RenameAsync(String desiredName, NameCollisionOption option)Public Function RenameAsync(desiredName As String, option As NameCollisionOption) As IAsyncActionpublic IAsyncAction RenameAsync(String desiredName, NameCollisionOption option)
Parameters
desiredName
System.String System.String System.String System.String

The desired, new name of the current file.

If there is an existing item in the current file's location that already has the specified desiredName, the specified NameCollisionOption determines how Windows responds to the conflict.

option
NameCollisionOption NameCollisionOption NameCollisionOption NameCollisionOption

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

Returns

No object or value is returned by this method when it completes.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

ReplaceWithStreamedFileAsync(IStorageFile, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) ReplaceWithStreamedFileAsync(IStorageFile, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) ReplaceWithStreamedFileAsync(IStorageFile, StreamedFileDataRequestedHandler, IRandomAccessStreamReference) ReplaceWithStreamedFileAsync(IStorageFile, StreamedFileDataRequestedHandler, IRandomAccessStreamReference)

Replaces the contents of the file referred to by the specified IStorageFile object with a new data stream. This method lets the app produce the data on-demand by specifying a function to be invoked when the StorageFile that represents the stream is first accessed.

public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileAsync(IStorageFile fileToReplace, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileAsync(IStorageFile fileToReplace, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)Public Static Function ReplaceWithStreamedFileAsync(fileToReplace As IStorageFile, dataRequested As StreamedFileDataRequestedHandler, thumbnail As IRandomAccessStreamReference) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileAsync(IStorageFile fileToReplace, StreamedFileDataRequestedHandler dataRequested, IRandomAccessStreamReference thumbnail)
Parameters
fileToReplace
IStorageFile IStorageFile IStorageFile IStorageFile

The file (type IStorageFile ) that the new data stream should be written to.

dataRequested
StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler StreamedFileDataRequestedHandler

The function that should be invoked when the StorageFile that is returned is first accessed. This function should produce the data stream represented by the returned StorageFile and lets the app produce data on-demand instead of writing the contents of the file at creation time.

thumbnail
IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference

The thumbnail image for the StorageFile to create.

For a high-quality thumbnail, one edge of this thumbnail should be at least 1024 pixels.

Returns

When this method completes, it returns a StorageFile object that represents the new data stream. Subsequently, this StorageFile object should be used to access file content instead of the file (type IStorageFile ) that was specified to be replace.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary

Remarks

This method lets you defer expensive operations to produce the data until that data needed (when it is first accessed). This avoids creating unnecessary delays in user interaction while the data is produced.

ReplaceWithStreamedFileFromUriAsync(IStorageFile, Uri, IRandomAccessStreamReference) ReplaceWithStreamedFileFromUriAsync(IStorageFile, Uri, IRandomAccessStreamReference) ReplaceWithStreamedFileFromUriAsync(IStorageFile, Uri, IRandomAccessStreamReference) ReplaceWithStreamedFileFromUriAsync(IStorageFile, Uri, IRandomAccessStreamReference)

Replaces the contents of the file referred to by the specified IStorageFile object with a new data stream of the specified Uniform Resource Identifier (URI). This method lets the app download the data on-demand when the StorageFile that represents the stream is first accessed.

The data stream is accessed through the StorageFile that is returned and the data is downloaded on-demand when the StorageFile is first accessed.

Replaces the IStorageFile object that represents the specified file with a new StorageFile that provides a stream of the specified Uniform Resource Identifier (URI).

public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileFromUriAsync(IStorageFile fileToReplace, Uri uri, IRandomAccessStreamReference thumbnail)public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileFromUriAsync(IStorageFile fileToReplace, Uri uri, IRandomAccessStreamReference thumbnail)Public Static Function ReplaceWithStreamedFileFromUriAsync(fileToReplace As IStorageFile, uri As Uri, thumbnail As IRandomAccessStreamReference) As IAsyncOperation( Of StorageFile )public static IAsyncOperation<StorageFile> ReplaceWithStreamedFileFromUriAsync(IStorageFile fileToReplace, Uri uri, IRandomAccessStreamReference thumbnail)
Parameters
fileToReplace
IStorageFile IStorageFile IStorageFile IStorageFile

The file that the created StorageFile will provide a stream of.

uri
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the resource used to create the StorageFile.

thumbnail
IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference

The thumbnail image for the StorageFile to create.

For a high-quality thumbnail, one edge of this thumbnail should be at least 1024 pixels.

Returns

When this method completes, it returns a StorageFile object that represents the streamed file. Subsequently, this StorageFile object should be used to access file content instead of the file (type IStorageFile ) that was specified to be replace.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
documentsLibrary musicLibrary videosLibrary picturesLibrary