Iniciar o app padrão para um arquivo

APIs importantes

• Windows.System.Launcher.LaunchFileAsync

Aprenda como iniciar o app padrão para um arquivo. Muitos aplicativos precisam trabalhar com arquivos que não conseguem lidar sozinhos. Por exemplo, os aplicativos de email recebem uma variedade de tipos de arquivo e precisam de uma maneira de iniciar esses arquivos em seus manipuladores padrão. Estas etapas mostram como usar a API Windows.System.Launcher para iniciar o manipulador padrão de um arquivo que seu aplicativo não pode manipular sozinho.

Obter o objeto de arquivo

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

Se o arquivo estiver incluído no pacote do seu aplicativo, você poderá usar a propriedade Package.InstalledLocation para obter um objeto 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.

Inicie o arquivo

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

Inicialização padrão

Chame 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, que está 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
   }
}

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

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

Abrir com lançamento

Chame o método Windows.System.Launcher.LaunchFileAsync(IStorageFile, LauncherOptions) com LauncherOptions.DisplayApplicationPicker definido como true para iniciar o aplicativo selecionado no

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 junto com um comando alternativo na AppBar ou em um menu de contexto para permitir que o usuário 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
   }
}

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)

      If success Then
         ' File launched
      Else
         ' File launch failed
      End If
   Else
      ' Could not find file
   End If
End Sub

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 um substituto de aplicativo recomendado

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 pesquisar um aplicativo apropriado na loja. Se você quiser dar ao usuário uma recomendação específica para qual aplicativo adquirir nesse cenário, poderá fazê-lo passando essa recomendação junto com o arquivo que 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 na Loja que você deseja recomendar. Em seguida, defina o LauncherOptions.PreferredApplicationDisplayName como o nome desse aplicativo. O Windows usará essas informações para substituir a opção geral de pesquisar um aplicativo na loja por uma opção específica para adquirir o aplicativo recomendado 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
   }
}

async Sub DefaultLaunch()

   ' Path to the file in the app package to launch
   Dim imageFile = "images\test.contoso"

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

   If file IsNot Nothing Then
      ' Set the recommended app
      Dim options = 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
      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

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 exibição restante desejada (somente Windows)

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 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. Essa propriedade especifica apenas o tamanho preferencial da janela do aplicativo de chamada. Ela não especifica o comportamento de outros aplicativos que podem estar na tela ao mesmo tempo.

**Família de dispositivos móveis: **LauncherOptions.DesiredRemainingView não tem suporte na família de dispositivos móveis.

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 (Plataforma Universal do Windows) 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 inicializações de arquivo diretamente à interface do usuário do seu aplicativo. Provavelmente, o usuário deve sempre tomar alguma ação para iniciar a inicialização de um arquivo.

Você não pode iniciar tipos de arquivo que contenham código ou script se eles forem executados automaticamente pelo sistema operacional, como arquivos .exe, .msi e .js. Essa restrição protege os usuários de arquivos potencialmente maliciosos que podem modificar o sistema operacional. Você pode usar esse método para iniciar tipos de arquivo que podem conter script se forem executados por um aplicativo que isola o script, como arquivos .docx. Aplicativos como o Microsoft Word impedem que o script em arquivos .docx modifique o sistema operacional.

Se você tentar iniciar um tipo de arquivo restrito, a inicialização falhará e seu retorno de chamada de erro será invocado. Se o aplicativo lida com muitos tipos diferentes de arquivos e você espera encontrar esse erro, recomendamos que você forneça uma experiência de fallback ao usuário. Por exemplo, você pode dar ao usuário a opção de salvar o arquivo na área de trabalho e ele pode abri-lo lá.

Tópicos relacionados

Tarefas

• Iniciar o app padrão para um URI
• Manipular a ativação do arquivo

Diretrizes

• Diretrizes para tipos de arquivo e URIs

Referência

• Windows.Storage.StorageFile
• Windows.System.Launcher.LaunchFileAsync