Launcher.LaunchFileAsync Method
Definition
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.
Overloads
| LaunchFileAsync(IStorageFile) |
Starts the default app associated with the specified file. |
| LaunchFileAsync(IStorageFile, LauncherOptions) |
Starts the default app associated with the specified file, using the specified options. |
LaunchFileAsync(IStorageFile)
Starts the default app associated with the specified file.
public:
static IAsyncOperation<bool> ^ LaunchFileAsync(IStorageFile ^ file);/// [Windows.Foundation.Metadata.Overload("LaunchFileAsync")]
static IAsyncOperation<bool> LaunchFileAsync(IStorageFile const& file);[Windows.Foundation.Metadata.Overload("LaunchFileAsync")]
public static IAsyncOperation<bool> LaunchFileAsync(IStorageFile file);function launchFileAsync(file)Public Shared Function LaunchFileAsync (file As IStorageFile) As IAsyncOperation(Of Boolean)Parameters
- file
- IStorageFile
The file.
Returns
The launch operation.
- Attributes
Examples
This example uses LaunchFileAsync(IStorageFile) to launch a file contained in the app package.
async void DefaultLaunch()
{
// Path to the file in the app package to launch
string imageFile = @"images\test.png";
var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);
if (file != null)
{
// Launch the retrieved file
var success = await Windows.System.Launcher.LaunchFileAsync(file);
if (success)
{
// File launched
}
else
{
// File launch failed
}
}
else
{
// Could not find file
}
}
Windows::Foundation::IAsyncAction MainPage::DefaultLaunch()
{
// Get the app's installation folder.
Windows::Storage::StorageFolder installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };
Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"Assets\\LockScreenLogo.scale-200.png") };
if (file)
{
// Launch the retrieved file.
bool success{ co_await Windows::System::Launcher::LaunchFileAsync(file) };
if (success)
{
// File launched.
}
else
{
// File launch failed.
}
}
else
{
// Couldn't find file.
}
}
void MainPage::DefaultLaunch()
{
auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
getFileOperation.then([](Windows::Storage::StorageFile^ file)
{
if (file != nullptr)
{
// Launch the retrieved file
concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file));
launchFileOperation.then([](bool success)
{
if (success)
{
// File launched
}
else
{
// File launch failed
}
});
}
else
{
// Could not find file
}
});
}
async Sub DefaultLaunch()
' Path to the file in the app package to launch
Dim imageFile = "images\test.png"
Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)
If file IsNot Nothing Then
' Launch the retrieved file
Dim success = await Windows.System.Launcher.LaunchFileAsync(file)
If success Then
' File launched
Else
' File launch failed
End If
Else
' Could not find file
End If
End Sub
Remarks
The calling app must be visible to the user when the API is invoked.
This API must be called from an ASTA thread (also known as a UI thread).
This API also imposes several restrictions on what types of files it can launch. Many file types that contain executable code, for example .exe, .msi, and .js files, are blocked from launching. This restriction protects users from potentially malicious files that could modify the system.
When the launch fails for any of the above reasons, the API succeeds and returns FALSE from its asynchronous operation. Since it has no ability to query whether the above restrictions apply to the current launch, the calling app should not assume that the launch succeeded, and should provide fallback mechanism in case it failed. A possible solution would be to ask the user to save the file and direct the user to open it in the desktop.
To enable the user to choose an app instead of launching the default app, set the LauncherOptions.DisplayApplicationPicker property.
To display a warning that the file is potentially unsafe, set the LauncherOptions.TreatAsUntrusted property.
The file is passed to the associated app. If the associated app is a desktop app, the file is passed using shell execution mechanisms.
See also
- LaunchFileAsync(IStorageFile, LauncherOptions)
- Association launching sample
- Guidelines for file types and URIs
- Launch the default app for a file
Applies to
LaunchFileAsync(IStorageFile, LauncherOptions)
Starts the default app associated with the specified file, using the specified options.
public:
static IAsyncOperation<bool> ^ LaunchFileAsync(IStorageFile ^ file, LauncherOptions ^ options);/// [Windows.Foundation.Metadata.Overload("LaunchFileWithOptionsAsync")]
static IAsyncOperation<bool> LaunchFileAsync(IStorageFile const& file, LauncherOptions const& options);[Windows.Foundation.Metadata.Overload("LaunchFileWithOptionsAsync")]
public static IAsyncOperation<bool> LaunchFileAsync(IStorageFile file, LauncherOptions options);function launchFileAsync(file, options)Public Shared Function LaunchFileAsync (file As IStorageFile, options As LauncherOptions) As IAsyncOperation(Of Boolean)Parameters
- file
- IStorageFile
The file.
- options
- LauncherOptions
The launch options for the app.
Returns
The launch operation.
- Attributes
Examples
Call the [Launcher.LaunchFileAsync(IStorageFile, LauncherOptions) method with LauncherOptions.DisplayApplicationPicker set to true to launch the app that the user selects for the file from the Open With dialog box.
async void DefaultLaunch()
{
// Path to the file in the app package to launch
string imageFile = @"images\test.png";
var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);
if (file != null)
{
// Set the option to show the picker
var options = new Windows.System.LauncherOptions();
options.DisplayApplicationPicker = true;
// Launch the retrieved file
bool success = await Windows.System.Launcher.LaunchFileAsync(file, options);
if (success)
{
// File launched
}
else
{
// File launch failed
}
}
else
{
// Could not find file
}
}
Windows::Foundation::IAsyncAction MainPage::DefaultLaunch()
{
// Get the app's installation folder.
Windows::Storage::StorageFolder installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };
Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"Assets\\LockScreenLogo.scale-200.png") };
if (file)
{
// Set the option to show the picker.
Windows::System::LauncherOptions launcherOptions;
launcherOptions.DisplayApplicationPicker(true);
// Launch the retrieved file.
bool success{ co_await Windows::System::Launcher::LaunchFileAsync(file, launcherOptions) };
if (success)
{
// File launched.
}
else
{
// File launch failed.
}
}
else
{
// Couldn't find file.
}
}
void MainPage::DefaultLaunch()
{
auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.png"));
getFileOperation.then([](Windows::Storage::StorageFile^ file)
{
if (file != nullptr)
{
// Set the option to show the picker
auto launchOptions = ref new Windows::System::LauncherOptions();
launchOptions->DisplayApplicationPicker = true;
// Launch the retrieved file
concurrency::task<bool> launchFileOperation(Windows::System::Launcher::LaunchFileAsync(file, launchOptions));
launchFileOperation.then([](bool success)
{
if (success)
{
// File launched
}
else
{
// File launch failed
}
});
}
else
{
// Could not find file
}
});
}
async Sub DefaultLaunch()
' Path to the file in the app package to launch
Dim imageFile = "images\test.png"
Dim file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile)
If file IsNot Nothing Then
' Set the option to show the picker
Dim options = Windows.System.LauncherOptions()
options.DisplayApplicationPicker = True
' Launch the retrieved file
Dim success = await Windows.System.Launcher.LaunchFileAsync(file, options)
If success Then
' File launched
Else
' File launch failed
End If
Else
' Could not find file
End If
End Sub
Remarks
The calling app must be visible to the user when the API is invoked.
This API must be called from within an ASTA thread (also known as a UI thread).
This API also imposes several restrictions on what types of files it can launch. Many file types that contain executable code, for example .exe, .msi, and .js files, are blocked from launching. This restriction protects users from potentially malicious files that could modify the system.
When the launch fails for any of the above reasons, the API succeeds and returns FALSE from its asynchronous operation. Since it has no ability to query whether the above restrictions apply to the current launch, the calling app should not assume that the launch succeeded, and should provide fallback mechanism in case it failed. A possible solution would be to ask the user to save the file and direct the user to open it in the desktop.
To enable the user to choose an app instead of launching the default app, set the LauncherOptions.DisplayApplicationPicker property.
To display a warning that the file is potentially unsafe, set the LauncherOptions.TreatAsUntrusted property.
The file is passed to the associated app. If the associated app is a desktop app, the file is passed using shell execution mechanisms.
See also
Applies to
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for