Обработка активации URI

Узнайте, как зарегистрировать приложение, чтобы стать обработчиком по умолчанию для имени схемы универсального идентификатора ресурса (URI). Классические приложения Windows и приложения Универсальной платформы Windows (UWP) могут зарегистрировать себя в качестве обработчика по умолчанию для имени схемы URI. Если пользователь выбирает приложение в качестве обработчика по умолчанию для имени схемы URI, приложение будет активировано при каждом запуске типа URI.

Рекомендуется регистрировать имя схемы URI только в том случае, если вы собираетесь обрабатывать все запуски URI для этой схемы. Если вы решили зарегистрировать имя схемы URI, необходимо предоставить пользователю функциональность, которая ожидается при активации приложения для этой схемы URI. Например, приложение, которое регистрируется для имени схемы mailto: URI, должно открывать новое сообщение электронной почты, чтобы пользователь смог написать новое письмо. Дополнительные сведения о сопоставлениях URI см. в разделе "Файлы", "Папки" и "Библиотеки".

Данные шаги показывают, как зарегистрировать имя пользовательской схемы URI alsdk://и как активировать ваше приложение, когда пользователь запускает URI alsdk://.

Важные API

В этом разделе используются следующие API:

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs (аргументы события активации протокола)
• Windows.UI.Xaml.Application.OnActivated
• AppInstance.GetActivatedEventArgs

Шаг 1. Указание точки расширения в манифесте пакета

Приложение получает события активации только для имен схем URI, перечисленных в манифесте пакета. Вот как указать, что ваше приложение обрабатывает имя схемы URI alsdk.

1. В обозревателе решений дважды щелкните package.appxmanifest, чтобы открыть конструктор манифестов. Выберите вкладку Декларации и в раскрывающемся списке Доступные декларации выберите Протокол , а затем нажмите кнопку Добавить.

   Ниже приведено краткое описание каждого из полей, которые можно заполнить конструктором манифестов для протокола (дополнительные сведения см. в манифесте пакета AppX ):

2. Введите images\Icon.png как логотип .

3. Введите SDK Sample URI Scheme в качестве отображаемого имени

4. Введите alsdk в качестве имени .

5. Нажмите клавиши CTRL+S, чтобы сохранить изменение в package.appxmanifest.

   При этом в манифест пакета добавляется элемент Extension , подобный этому элементу. Категория windows.protocol указывает, что приложение обрабатывает имя схемы URI alsdk.

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   </Applications>

Шаг 2. Добавление соответствующих значков

Иконки приложений, которые становятся используемыми по умолчанию для схемы URI, отображаются во многих местах в системе, например, на панели управления в разделе "Программы по умолчанию". Добавьте значок 44x44 в проект для этой цели. Сопоставляйте внешний вид логотипа плитки приложения и используйте цвет фона приложения, а не прозрачный значок. Сделайте так, чтобы логотип доходил до края без отступов. Проверьте значки на белом фоне. Дополнительную информацию о значках приложений и логотипах см. в разделе Знаки и логотипы приложений.

Шаг 3. Обработка активированного события

В приложениях UWP обработчик событий OnActivated получает все события активации. Свойство Kind указывает тип события активации. Этот пример настраивается для обработки событий активации протокола .

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

Следующий код программно запускает приложение с помощью URI:

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri)

Дополнительные сведения о запуске приложения с помощью URI см. в разделе "Запуск приложения по умолчанию для URI".

Рекомендуется, чтобы приложения создавали новый компонент XAML Frame для каждого события активации, которое открывает новую страницу. Таким образом, стек навигации для нового XAML кадра не будет содержать никакого предыдущего содержимого, которое приложение могло иметь в текущем окне в момент приостановки. Приложения, которые решили использовать один кадра XAML для запуска и файловых контрактов, должны очистить страницы в журнале навигациикадра перед переходом на новую страницу.

При запуске с помощью активации протокола приложения следует рассмотреть возможность включения пользовательского интерфейса, позволяющего пользователю вернуться на верхнюю страницу приложения.

Замечания

Любое приложение или веб-сайт может использовать имя схемы URI, включая вредоносные программы. Таким образом, любые данные, полученные в URI, могут поступать из ненадежного источника. Мы рекомендуем никогда не совершать постоянных действий на основе параметров, которые вы получаете в URI. Например, параметры URI можно использовать для запуска приложения на странице учетной записи пользователя, но мы рекомендуем никогда не использовать их для непосредственного изменения учетной записи пользователя.

Мы рекомендуем приложениям создать новую XAML Frame для каждого события активации, которое открывает новый URI-целевой объект. Таким образом, стек навигации для нового XAML кадра не будет содержать никакого предыдущего содержимого, которое приложение могло иметь в текущем окне в момент приостановки.

Если вы решите, что приложения должны использовать один кадр XAML для контрактов запуска и протокола, очистите страницы из журнала навигации кадра перед навигацией на новую страницу. При запуске с помощью контракта протокола рассмотрите возможность включения пользовательского интерфейса в приложения, которые позволяют пользователю вернуться в начало приложения.

Связанный контент

• Образец запуска приложения UWP от ассоциации
• Программы по умолчанию
• Обработка активации файлов