Передача параметров установки в приложение с помощью установщика приложенийPassing installation parameters to your app via App Installer
При распространении приложения с помощью MSIX можно настроить приложение таким, чтобы параметры строки запроса, определяемые в URI скачивания или установки, передавались приложению при запуске, после того как пользователь щелкнет URI скачивания или установки.When distributing your app using MSIX you can configure your app such that query string parameters you define in the download/install uri are passed on to your app when it launches, after a user clicks on the download/install uri. Это работает, когда пользователь впервые устанавливает приложение или если приложение было установлено ранее.This works whether it's the first time a user is installing the app or if the app was previously installed. В этой статье показано, как настроить упакованное приложение MSIX и его URI для скачивания и установки, чтобы воспользоваться преимуществами этой функции.This article shows how to configure your MSIX packaged application and its download/install uri to take advantage of this functionality. Это может быть полезно, если требуется относить или обрабатывать различные установки на основе источника, загрузки типа и т. д., а также для загрузки веб-страниц и других случаев, когда пользователь щелкает URI, например из кампании по электронной почте.This can be useful if you want to track or handle different installs based on the source, download type etc and will work for web downloads, and any other cases where a user clicks the uri e.g. from an email campaign. Дополнительные сведения см. в этой записи блога.For more details check out this blog post.
Настройка приложения для активации протоколаConfigure your application for protocol activation
Первое, что нужно сделать, — зарегистрировать приложение для запуска с помощью настраиваемого протокола , который вы определили.The first thing to do is to register your app for it to be launched using a custom protocol you define. При вызове этого протокола приложение запускается и все праметерс, указанные в URI, передаются в аргументы события активации приложения при его запуске.When this protocol is invoked, your application is launched and any prameters specified in the uri are passed to your app's activation event arguments when it is launched. Вы можете зарегистрировать протокол, добавив запись расширения протокола в узел расширения приложения в файле appxmanifest.xml MSIX:You can register the protocol by adding a protocol extension entry in the Application Extensions node in your MSIX's appxmanifest.xml file:
<Application>
...
<Extensions>
<uap:Extension Category="windows.protocol">
<uap:Protocol Name="my-custom-protocol"/>
</uap:Extension>
</Extensions>
...
</Application>
Если вы используете проект упаковки Windows, можно также определить пользовательский протокол с помощью редактора манифестов по умолчанию, дважды щелкнув файл Package. appxmanifest , перейдя на вкладку объявления и выбрав протокол в списке Доступные объявления:If you are using the Windows Packaging Project, you can also define a custom protocol using the default manifest editor by double clicking the package.appxmanifest file, navigating to the Declarations tab and selecting Protocol under Available Declarations:
Написание кода для управления параметрами при запуске приложения после установкиWrite code to handle parameters when your app is launched after installation
Необходимо реализовать код в приложении, чтобы обрабатывать параметры установки, которые будут переданы в приложение при его запуске.You will need to implement code in your application to handle the installation parameters that will be passed to your app when it is launched. В приведенном ниже примере кода используется метод аппинстанце. жетактиватедевентаргс для определения типа активации, используемого для создания экземпляра приложения (можно также выполнять обработку параметров с помощью другого метода).The example code below uses the AppInstance.GetActivatedEventArgs method to determine the type of activation used to instantiate an app (you can also handle the parameters using a different method). Когда приложение запускается или активируется с помощью параметров проверочного запросов из URI установки (см. Описание определения в следующем разделе), тип активации будет активироваться протоколом, как определено настраиваемым протоколом, объявленным в appxmanifest.xml и скачать/установить URI.When your app is launched/activated with query sting parameters from an install uri (see defintion in the next section), the activation type will be a protocol activation as defined by your custom protocol declared in your appxmanifest.xml and download/install uri. Аргументы события активации будут иметь тип протоколактиватедевентаргс , который используется в коде, приведенном ниже.The activation event args will be of type ProtocolActivatedEventArgs and that is what the code below uses:
using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;
public static void Main(string[] cmdArgs)
{
var activationArgs = AppInstance.GetActivatedEventArgs();
switch (activationArgs.Kind)
{
//Install parameters will be passed in during a protocol activation
case ActivationKind.Protocol:
HandleProtocolActivation(activationArgs as ProtocolActivatedEventArgs);
break;
case ActivationKind.Launch:
//Regular launch activation type
HandleLaunch(activationArgs as LaunchActivatedEventArgs);
break;
default:
break;
}
static void HandleProtocolActivation(ProtocolActivatedEventArgs args)
{
if (args.Uri != null)
{
//Handle the installation parameters in the protocol uri
handleInstallParameter(args.Uri.ToString());
}
}
Добавление пользовательского протокола активации и параметров в URI установкиAdd your custom activation protocol and parameters to the installation uri
После того как приложение настроено для работы с параметрами установки, можно настроить URI скачивания и установки приложения, чтобы он содержал уникальные параметры, которые будут переданы в приложение при запуске, после того, как пользователь щелкнет URI.Once your app is set up to handle your installation parameters, you can customise the app download/install uri to contain uniquely defined parameters that will be passed on to your app at launch, after a user clicks on the uri. URI должен содержать:The uri must contain:
- Протокол MS-appinstaller , который вызывает установщик приложения.The ms-appinstaller protocol that invokes App Installer.
- Уникальный параметр активатионури , указывающий на пользовательский протокол приложения и параметры установки, которые необходимо передать в приложение при его запуске.The unique parameter activationUri that points to your app's custom protocol and the install parameters you want passed to your app when it is launched.
- Настраиваемый протокол приложения, а также параметр и его значение.Your app's custom protocol and the the parameter and its value.
В приведенных ниже примерах универсальных кодов ресурса (URI) я определил настраиваемый протокол My-Custom-Protocol, параметр My-Parameter и присвоить ему значение My-PARAM-value.In the example uris below, I have defined a custom protocol my-custom-protocol, a parameter my-parameter and given it the value my-param-value. Когда приложение запускается после того, как пользователь щелкнет универсальный код ресурса (URI), он получит часть строки запроса в URI после активатионури, в этом случае это будет мой пользовательский параметр — протокол:? My-Parameter = My-PARAM-value.When the app is launched after a user clicks on the uri, it will receive the query string portion of the uri after activationUri, in this case that will be my-custom-protocol:?my-parameter=my-param-value.
ms-appinstaller:?source=https://contoso.com/myapp.appinstaller&activationUri=my-custom-protocol:?my-parameter=my-param-value
ms-appinstaller:?source=https://contos.com/myapp.msix&activationUri=my-custom-protocol:?my-parameter=my-param-value