StorageFile.CopyAsync Method
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
| CopyAsync(IStorageFolder) |
Creates a copy of the file in the specified folder. |
| CopyAsync(IStorageFolder, String) |
Creates a copy of the file in the specified folder and renames the copy. |
| 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. |
Creates a copy of the file in the specified folder.
public:
virtual IAsyncOperation<StorageFile ^> ^ CopyAsync(IStorageFolder ^ destinationFolder) = CopyAsync;/// [Windows.Foundation.Metadata.Overload("CopyOverloadDefaultNameAndOptions")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<StorageFile> CopyAsync(IStorageFolder const& destinationFolder);[Windows.Foundation.Metadata.Overload("CopyOverloadDefaultNameAndOptions")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder);function copyAsync(destinationFolder)Public Function CopyAsync (destinationFolder As IStorageFolder) As IAsyncOperation(Of StorageFile)Parameters
- destinationFolder
- 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.
Implements
- Attributes
Exceptions
You don't have permission to copy a file into the destination folder.
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);
IAsyncAction MainPage::CopyFileAsync()
{
// 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.
std::wstring newFileName{ L"test.txt" };
std::wstring copyFileName{ L"renamed_test.txt" };
// Create a sample file in the temporary folder.
StorageFile sourceFile{ co_await sourceFolder.CreateFileAsync(newFileName, Windows::Storage::CreationCollisionOption::ReplaceExisting) };
// Overwrite any existing file with the same name.
StorageFile copiedFile{ co_await sourceFile.CopyAsync(targetFolder, copyFileName, Windows::Storage::NameCollisionOption::ReplaceExisting) };
// Do something with copied file.
}
//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 existing 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
});
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.
Note
When StorageFile.CopyAsync is used to copy a file that is encrypted to a destination that is not encrypted, the call will fail with the following exception: System.UnauthorizedAccessException: Access is denied. (Excep_FromHResult 0x80070005)
See also
Applies to
WinRT Build 26100 and other versions
| Product | Versions |
|---|---|
| WinRT | Build 10240, Build 10586, Build 14383, Build 15063, Build 16299, Build 17134, Build 17763, Build 18362, Build 19041, Build 20348, Build 22000, Build 22621, Build 26100 |
Creates a copy of the file in the specified folder and renames the copy.
public:
virtual IAsyncOperation<StorageFile ^> ^ CopyAsync(IStorageFolder ^ destinationFolder, Platform::String ^ desiredNewName) = CopyAsync;/// [Windows.Foundation.Metadata.Overload("CopyOverloadDefaultOptions")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<StorageFile> CopyAsync(IStorageFolder const& destinationFolder, winrt::hstring const& desiredNewName);[Windows.Foundation.Metadata.Overload("CopyOverloadDefaultOptions")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, string desiredNewName);function copyAsync(destinationFolder, desiredNewName)Public Function CopyAsync (destinationFolder As IStorageFolder, desiredNewName As String) As IAsyncOperation(Of StorageFile)Parameters
- destinationFolder
- IStorageFolder
The destination folder where the copy of the file is created.
- desiredNewName
-
String
Platform::String
winrt::hstring
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.
Note
When StorageFile.CopyAsync is used to copy a file that is encrypted to a destination that is not encrypted, the call will fail with the following exception: System.UnauthorizedAccessException: Access is denied. (Excep_FromHResult 0x80070005)
Implements
- Attributes
Exceptions
You don't have permission to copy a file into the destination folder.
See also
Applies to
WinRT Build 26100 and other versions
| Product | Versions |
|---|---|
| WinRT | Build 10240, Build 10586, Build 14383, Build 15063, Build 16299, Build 17134, Build 17763, Build 18362, Build 19041, Build 20348, Build 22000, Build 22621, Build 26100 |
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:
virtual IAsyncOperation<StorageFile ^> ^ CopyAsync(IStorageFolder ^ destinationFolder, Platform::String ^ desiredNewName, NameCollisionOption option) = CopyAsync;/// [Windows.Foundation.Metadata.Overload("CopyOverload")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<StorageFile> CopyAsync(IStorageFolder const& destinationFolder, winrt::hstring const& desiredNewName, NameCollisionOption const& option);[Windows.Foundation.Metadata.Overload("CopyOverload")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<StorageFile> CopyAsync(IStorageFolder destinationFolder, string desiredNewName, NameCollisionOption option);function copyAsync(destinationFolder, desiredNewName, option)Public Function CopyAsync (destinationFolder As IStorageFolder, desiredNewName As String, option As NameCollisionOption) As IAsyncOperation(Of StorageFile)Parameters
- destinationFolder
- IStorageFolder
The destination folder where the copy of the file is created.
- desiredNewName
-
String
Platform::String
winrt::hstring
The new name for the copy of the file created in the destinationFolder.
- option
- 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.
Note
When StorageFile.CopyAsync is used to copy a file that is encrypted to a destination that is not encrypted, the call will fail with the following exception: System.UnauthorizedAccessException: Access is denied. (Excep_FromHResult 0x80070005)
Implements
- Attributes
Exceptions
You don't have permission to copy a file into the destination folder.
See also
Applies to
WinRT Build 26100 and other versions
| Product | Versions |
|---|---|
| WinRT | Build 10240, Build 10586, Build 14383, Build 15063, Build 16299, Build 17134, Build 17763, Build 18362, Build 19041, Build 20348, Build 22000, Build 22621, Build 26100 |