Iniciar o aplicativo padrão para um arquivo

Saiba como iniciar a aplicação predefinida para um ficheiro a partir da sua WinUI, da Plataforma Universal do Windows (UWP) ou de outra aplicação de ambiente de trabalho. Muitos aplicativos precisam trabalhar com arquivos que eles mesmos não conseguem manipular. Por exemplo, os aplicativos de email recebem uma variedade de tipos de arquivos e precisam de uma maneira de iniciar esses arquivos em seus manipuladores padrão. Estas etapas mostram como usar o Windows.System.Launcher API do Tempo de Execução do Windows (WinRT) para iniciar o manipulador padrão para um arquivo que seu aplicativo não pode manipular sozinho.

APIs importantes

As seguintes APIs são apresentadas neste tópico:

• Windows.System.Launcher.LaunchFileAsync

Obter o objeto de arquivo

Primeiro, obtenha um objeto Windows.Storage.StorageFile para o ficheiro.

Se o arquivo estiver incluído no pacote da sua aplicação, pode usar a propriedade Package.InstalledLocation para obter um objeto do tipo Windows.Storage.StorageFolder e o método Windows.Storage.StorageFolder.GetFileAsync para obter o objeto StorageFile.

Se o arquivo estiver em uma pasta conhecida, você poderá usar as propriedades da classe Windows.Storage.KnownFolders para obter um StorageFolder e o método GetFileAsync para obter o objeto StorageFile.

Iniciar o arquivo

O Windows fornece várias opções diferentes para iniciar o manipulador padrão para um arquivo. Essas opções são descritas neste gráfico e nas seções a seguir.

Inicialização padrão

Utilize o método Windows.System.Launcher.LaunchFileAsync(IStorageFile) para iniciar o aplicativo padrão. Este exemplo usa o método Windows.Storage.StorageFolder.GetFileAsync para iniciar um arquivo de imagem, test.png, incluído no pacote do aplicativo.

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()
{
    auto installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

    Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"images\\test.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
    {
        // Could not 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
      }
   });
}

Aberto com lançamento

Chame o método Windows.System.Launcher.LaunchFileAsync(IStorageFile, LauncherOptions) com LauncherOptions.DisplayApplicationPicker definido como true para iniciar o aplicativo que o usuário seleciona na caixa de diálogo 'Abrir com' .

Recomendamos que você use a caixa de diálogo Abrir com quando o usuário quiser selecionar um aplicativo diferente do padrão para um arquivo específico. Por exemplo, se seu aplicativo permitir que o usuário inicie um arquivo de imagem, o manipulador padrão provavelmente será um aplicativo visualizador. Em alguns casos, o usuário pode querer editar a imagem em vez de visualizá-la. Use a opção Abrir com juntamente com um comando alternativo na AppBar ou num menu de contexto para permitir que o utilizador abra a caixa de diálogo Abrir com e selecione o aplicativo editor nesses tipos de cenários.

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()
{
    auto installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

    Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"images\\test.png") };

    if (file)
    {
        // Set the option to show the picker
        Windows::System::LauncherOptions launchOptions;
        launchOptions.DisplayApplicationPicker(true);

        // Launch the retrieved file
        bool success = co_await Windows::System::Launcher::LaunchFileAsync(file, launchOptions);
        if (success)
        {
            // File launched
        }
        else
        {
            // File launch failed
        }
    }
    else
    {
        // Could not 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
      }
   });
}

Iniciar com uma aplicação alternativa recomendada

Em alguns casos, o usuário pode não ter um aplicativo instalado para lidar com o arquivo que você está iniciando. Por padrão, o Windows lidará com esses casos fornecendo ao usuário um link para procurar um aplicativo apropriado na loja. Se você gostaria de dar ao usuário uma recomendação específica para qual aplicativo adquirir neste cenário, você pode fazê-lo passando essa recomendação junto com o arquivo que você está iniciando. Para fazer isso, chame o método Windows.System.Launcher.launchFileAsync(IStorageFile, LauncherOptions) com LauncherOptions.PreferredApplicationPackageFamilyName definido como o nome da família de pacotes do aplicativo da Loja que você deseja recomendar. Em seguida, defina o LauncherOptions.PreferredApplicationDisplayName para o nome desse aplicativo. O Windows utilizará estas informações para substituir a opção geral de procurar uma aplicação na loja por uma opção específica para adquirir a aplicação recomendada na Loja.

async void DefaultLaunch()
{
   // Path to the file in the app package to launch
   string imageFile = @"images\test.contoso";

   // Get the image file from the package's image directory
   var file = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(imageFile);

   if (file != null)
   {
      // Set the recommended app
      var options = new Windows.System.LauncherOptions();
      options.PreferredApplicationPackageFamilyName = "Contoso.FileApp_8wknc82po1e";
      options.PreferredApplicationDisplayName = "Contoso File App";

      // Launch the retrieved file pass in the recommended app
      // in case the user has no apps installed to handle the 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()
{
    auto installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

    Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"images\\test.png") };

    if (file)
    {
        // Set the recommended app
        Windows::System::LauncherOptions launchOptions;
        launchOptions.PreferredApplicationPackageFamilyName(L"Contoso.FileApp_8wknc82po1e");
        launchOptions.PreferredApplicationDisplayName(L"Contoso File App");

        // Launch the retrieved file, and pass in the recommended app
        // in case the user has no apps installed to handle the file.
        bool success = co_await Windows::System::Launcher::LaunchFileAsync(file, launchOptions);
        if (success)
        {
            // File launched
        }
        else
        {
            // File launch failed
        }
    }
    else
    {
        // Could not find file
    }
}

void MainPage::DefaultLaunch()
{
   auto installFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

   concurrency::task<Windows::Storage::StorageFile^> getFileOperation(installFolder->GetFileAsync("images\\test.contoso"));
   getFileOperation.then([](Windows::Storage::StorageFile^ file)
   {
      if (file != nullptr)
      {
         // Set the recommended app
         auto launchOptions = ref new Windows::System::LauncherOptions();
         launchOptions->PreferredApplicationPackageFamilyName = "Contoso.FileApp_8wknc82po1e";
         launchOptions->PreferredApplicationDisplayName = "Contoso File App";
         
         // Launch the retrieved file pass, and in the recommended app
         // in case the user has no apps installed to handle the 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
      }
   });
}

Iniciar com uma Visualização Restante Desejada (somente UWP)

Os aplicativos de origem que chamam LaunchFileAsync podem solicitar que permaneçam na tela após a inicialização de um arquivo. Por padrão, o Windows tenta compartilhar todo o espaço disponível igualmente entre o aplicativo de origem e o aplicativo de destino que manipula o arquivo. Os aplicativos de origem podem usar a propriedade DesiredRemainingView para indicar ao sistema operacional que preferem que a janela do aplicativo ocupe mais ou menos do espaço disponível. DesiredRemainingView também pode ser usado para indicar que o aplicativo de origem não precisa permanecer na tela após a inicialização do arquivo e pode ser completamente substituído pelo aplicativo de destino. Esta propriedade especifica apenas o tamanho da janela preferencial do aplicativo de chamada. Ele não especifica o comportamento de outros aplicativos que também podem estar na tela ao mesmo tempo.

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 desired remaining view
      var options = new Windows.System.LauncherOptions();
      options.DesiredRemainingView = Windows.UI.ViewManagement.ViewSizePreference.UseLess;

      // 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()
{
    auto installFolder{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

    Windows::Storage::StorageFile file{ co_await installFolder.GetFileAsync(L"images\\test.png") };

    if (file)
    {
        // Set the desired remaining view.
        Windows::System::LauncherOptions launchOptions;
        launchOptions.DesiredRemainingView(Windows::UI::ViewManagement::ViewSizePreference::UseLess);

        // Launch the retrieved file.
        bool success = co_await Windows::System::Launcher::LaunchFileAsync(file, launchOptions);
        if (success)
        {
            // File launched
        }
        else
        {
            // File launch failed
        }
    }
    else
    {
        // Could not 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 desired remaining view.
         auto launchOptions = ref new Windows::System::LauncherOptions();
         launchOptions->DesiredRemainingView = Windows::UI::ViewManagement::ViewSizePreference::UseLess;

         // 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
      }
   });
}

Comentários

Seu aplicativo não pode selecionar o aplicativo que é iniciado. O usuário determina qual aplicativo é iniciado. O usuário pode selecionar um aplicativo UWP ou um aplicativo da área de trabalho do Windows.

Ao iniciar um arquivo, seu aplicativo deve ser o aplicativo em primeiro plano, ou seja, deve estar visível para o usuário. Esse requisito ajuda a garantir que o usuário permaneça no controle. Para atender a esse requisito, certifique-se de vincular todas as iniciações de arquivo diretamente à interface do usuário do seu aplicativo. Muito provavelmente, o usuário sempre deve tomar alguma ação para iniciar uma inicialização de arquivo.

Não é possível iniciar tipos de arquivo que contenham código ou script se eles forem executados automaticamente pelo sistema operacional, como arquivos .exe, .msie .js. Essa restrição protege os usuários contra arquivos potencialmente mal-intencionados que podem modificar o sistema operacional. Você pode usar esse método para iniciar tipos de arquivo que podem conter script se eles forem executados por um aplicativo que isola o script, como, .docx arquivos. Aplicações como o Microsoft Word impedem que o script nos arquivos .docx modifique o sistema operativo.

Se tentar lançar um tipo de ficheiro restrito, a execução falhará e o seu callback de erro será invocado. Se a sua aplicação lida com muitos tipos diferentes de ficheiros e espera encontrar esse erro, recomendamos que forneça uma experiência alternativa aos seus utilizadores. Por exemplo, você pode dar ao usuário uma opção para salvar o arquivo na área de trabalho, e eles podem abri-lo lá.

Conteúdo relacionado

• Iniciar a aplicação padrão para um URI
• Manipular a ativação de ficheiros
• Windows.System.Launcher.LaunchFileAsync