Обработка активации файлаHandle file activation

Важные APIImportant APIs

Приложение можно зарегистрировать в качестве обработчика по умолчанию для файлов определенных типов.Your app can register to become the default handler for a certain file type. Это касается как классических приложений для Windows, так и приложений универсальной платформы Windows (UWP).Both Windows desktop applications and Universal Windows Platform (UWP) apps can register to be a default file handler. Если пользователь выбирает ваше приложение в качестве стандартного обработчика для какого-либо типа файлов, оно будет активироваться при запуске файлов этого типа.If the user chooses your app as the default handler for a certain file type, your app will be activated when that type of file is launched.

Мы рекомендуем регистрировать приложение в качестве обработчика по умолчанию для файлов определенного типа, только если планируется обрабатывать все запуски файлов этого типа.We recommend that you only register for a file type if you expect to handle all file launches for that type of file. Если файлы данного типа будут использоваться только внутри приложения, нет необходимости регистрировать его в качестве обработчика по умолчанию.If your app only needs to use the file type internally, then you don't need to register to be the default handler. Если вы все-таки решите зарегистрировать тип файла, необходимо предоставить пользователю функциональность, ожидаемую при активации вашего приложения для файлов этого типа.If you do choose to register for a file type, you must provide the end user with the functionality that is expected when your app is activated for that file type. Например, приложение для просмотра изображений может быть зарегистрировано для отображения JPG-файлов.For example, a picture viewer app may register to display a .jpg file. Подробнее о сопоставлениях файлов: Руководство по типам файлов и URI.For more info on file associations, see Guidelines for file types and URIs.

Далее показано, как зарегистрировать собственный тип файлов (.alsdk) и как активировать приложение при запуске ALSDK-файла пользователем.These steps show how to register for a custom file type, .alsdk, and how to activate your app when the user launches an .alsdk file.

Примечание  в приложениях универсальной платформы Windows, определенные URI и файл расширения зарезервированы для использования встроенных приложений и операционной системы.Note  In UWP apps, certain URIs and file extensions are reserved for use by built-in apps and the operating system. Попытки регистрации приложения с зарезервированным URI или расширением файла будут проигнорированы.Attempts to register your app with a reserved URI or file extension will be ignored. Дополнительные сведения об этом см. в статье Зарезервированные файлы и имена схем URI.For more information, see Reserved file and URI scheme names.

Шаг 1. Укажите точку расширения в манифесте пакетаStep 1: Specify the extension point in the package manifest

Приложение принимает события активации только для расширений файлов, указанных в манифесте пакета.The app receives activation events only for the file extensions listed in the package manifest. Указать, что ваше приложение обрабатывает файлы с расширением .alsdk, можно следующим образом:Here's how you indicate that your app handles the files with the .alsdk extension.

  1. В обозревателе решений дважды щелкните файл package.appxmanifest, чтобы открыть конструктор манифеста.In the Solution Explorer, double-click package.appxmanifest to open the manifest designer. Перейдите на вкладку Объявления и в раскрывающемся списке Доступные объявления выберите Сопоставление типов файлов и нажмите кнопку Добавить.Select the Declarations tab and in the Available Declarations drop-down, select File Type Associations and then click Add. Дополнительные сведения об идентификаторах, используемых в сопоставлениях файлов, см. в разделе о программных идентификаторах.See Programmatic Identifiers for more details of identifiers used by file associations.

    Далее приведено краткое описание каждого из полей, которые можно заполнить в конструкторе манифеста:Here is a brief description of each of the fields that you may fill in the manifest designer:

ПолеField ОписаниеDescription
Отображаемое имяDisplay Name Укажите отображаемое имя для группы типов файлов.Specify the display name for a group of file types. Это отображаемое имя используется для определения типа файла в разделе Выбор программ по умолчанию на панели управления.The display name is used to identify the file type in the Set Default Programs on the Control Panel.
ЛоготипLogo Укажите логотип, по которому можно будет определить тип файла на рабочем столе и в разделе Выбор программ по умолчанию на панели управления.Specify the logo that is used to identify the file type on the desktop and in the Set Default Programs on the Control Panel. Если логотип не указан, используется мелкий логотип приложения.If no Logo is specified, the application’s small logo is used.
ПодсказкаInfo Tip Укажите подсказку для группы типов файлов.Specify the info tip for a group of file types. Эта подсказка отображается, когда пользователь наводит указатель мыши на значок файла этого типа.This tool tip text appears when the user hovers on the icon for a file of this type.
NameName Выберите имя для группы типов файлов, которые имеют общие отображаемое имя, логотип, подсказку и флаги редактирования.Choose a name for a group of file types that share the same display name, logo, info tip, and edit flags. Выберите для группы такое имя, которое будет сохраняться неизменным при обновлении приложения.Choose a group name that can stay the same across app updates. Примечание. Все буквы имени должны быть строчными.Note The Name must be in all lower case letters.
Тип содержимогоContent Type Укажите тип содержимого MIME, например image/jpeg, для определенного типа файла.Specify the MIME content type, such as image/jpeg, for a particular file type. Важное примечание о допустимых типах содержимого. Ниже приведен алфавитный список типов содержимого MIME, которые невозможно ввести в манифест пакета, так как они являются зарезервирован или запрещен: приложения/force-download, application/octet-stream, приложения или неизвестен, application/x-msdownload.Important Note about allowed content types: Here is an alphabetic list of MIME content types that you cannot enter into the package manifest because they are either reserved or forbidden: application/force-download, application/octet-stream, application/unknown, application/x-msdownload.
Тип файлаFile type Укажите тип файла для регистрации с точкой в начале имени, например ".jpeg".Specify the file type to register for, preceded by a period, for example, “.jpeg”. Файл зарезервированные и запрещенные типы: См. в разделе URI зарезервированные имена схем и типов файлов для алфавитный список типов файлов для встроенных приложений, которые не удается зарегистрировать для приложений универсальной платформы Windows, так как они являются зарезервирован или запрещен.Reserved and forbidden file types: See Reserved URI scheme names and file types for an alphabetic list of file types for built-in apps that you can't register for your UWP apps because they are either reserved or forbidden.
  1. Введите alsdk в поле Имя.Enter alsdk as the Name.
  2. Введите .alsdk в поле Тип файла.Enter .alsdk as the File Type.
  3. Введите «образы\Icon.png» как логотип.Enter “images\Icon.png” as the Logo.
  4. Нажмите клавиши CTRL+S, чтобы сохранить изменения в файле package.appxmanifest.Press Ctrl+S to save the change to package.appxmanifest.

Шаги выше добавляют в манифест пакета элемент Extension указанного типа.The steps above add an Extension element like this one to the package manifest. Категория windows.fileTypeAssociation указывает, что приложение обрабатывает файлы с расширением .alsdk.The windows.fileTypeAssociation category indicates that the app handles files with the .alsdk extension.

      <Extensions>
        <uap:Extension Category="windows.fileTypeAssociation">
          <uap:FileTypeAssociation Name="alsdk">
            <uap:Logo>images\icon.png</uap:Logo>
            <uap:SupportedFileTypes>
              <uap:FileType>.alsdk</uap:FileType>
            </uap:SupportedFileTypes>
          </uap:FileTypeAssociation>
        </uap:Extension>
      </Extensions>

Шаг 2. Добавьте соответствующие значкиStep 2: Add the proper icons

Значки приложений, используемых по умолчанию для того или иного типа файла, отображаются в различных частях системы.Apps that become the default for a file type have their icons displayed in various places throughout the system. Например, эти значки можно увидеть:For example, these icons are shown in:

  • в представлении просмотра элементов, в контекстных меню и на ленте проводника;Windows Explorer Items View, context menus, and the Ribbon
  • на панели управления в разделе программ по умолчанию;Default programs Control Panel
  • в средстве выбора файлов;File picker
  • в результатах поиска на начальном экране.Search results on the Start screen

Добавьте в проект значок размером 44 x 44, чтобы ваш логотип отображался в этих расположениях.Include a 44x44 icon with your project so that your logo can appear in those locations. Вместо того чтобы делать фон значка прозрачным, используйте для логотипа на плитке приложения цвет, который совпадает с цветом фона самого приложения.Match the look of the app tile logo and use your app's background color rather than making the icon transparent. Растяните логотип до краев, не заполняя плитку.Have the logo extend to the edge without padding it. Проверьте, как выглядят значки на белом фоне.Test your icons on white backgrounds. Дополнительные сведения о значках см. в разделе Руководство по работе с ресурсами плиток и значков.See Guidelines for tile and icon assets for more details about icons.

Шаг 3. Обработать событие активацииStep 3: Handle the activated event

Обработчик событий OnFileActivated принимает все события активации файлов.The OnFileActivated event handler receives all file activation events.

protected override void OnFileActivated(FileActivatedEventArgs args)
{
       // TODO: Handle file activation
       // The number of files received is args.Files.Size
       // The name of the first file is args.Files[0].Name
}
Protected Overrides Sub OnFileActivated(ByVal args As Windows.ApplicationModel.Activation.FileActivatedEventArgs)
      ' TODO: Handle file activation
      ' The number of files received is args.Files.Size
      ' The name of the first file is args.Files(0).Name
End Sub
void App::OnFileActivated(Windows::ApplicationModel::Activation::FileActivatedEventArgs const& args)
{
    // TODO: Handle file activation.
    auto numberOfFilesReceived{ args.Files().Size() };
    auto nameOfTheFirstFile{ args.Files().GetAt(0).Name() };
}
void App::OnFileActivated(Windows::ApplicationModel::Activation::FileActivatedEventArgs^ args)
{
    // TODO: Handle file activation
    // The number of files received is args->Files->Size
    // The name of the first file is args->Files->GetAt(0)->Name
}

Примечание

При запуске с помощью файла контракта, убедитесь, что этой кнопки Назад направляет пользователя обратно на экран, который запустил приложение, а не к предыдущей содержимого приложения.When launched via File Contract, make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

Мы рекомендуем создать новый XAML кадра для каждого события активации, откроется новая страница.We recommend that you create a new XAML Frame for each activation event that opens a new page. Таким образом, частях навигации для нового кадра XAML не содержит любого предыдущего содержимого, которое приложение может иметь текущее окно при приостановке.That way, the navigation backstack for the new XAML Frame doesn't contain any previous content that the app might have on the current window when suspended. Если вы решили использовать один XAML кадра для запуска и для контрактов файл, затем удалите страниц в кадрав журнал переходов до перехода на новую страницу.If you decide to use a single XAML Frame for Launch and for File Contracts, then you should clear the pages in the Frame's navigation journal before navigating to a new page.

При запуске приложения с помощью файла активации, рекомендуется включить пользовательский Интерфейс, который пользователь может вернуться к верхней страницы приложения.When your app is launched via File activation, you should consider including UI that allows the user to go back to the top page of the app.

ПримечанияRemarks

Принимаемые вами файлы могут поступать из ненадежного источника.The files that you receive could come from an untrusted source. Мы рекомендуем проверять содержимое файла перед тем, как выполнять с ним какие-либо действия.We recommend that you validate the content of a file before taking action on it.

Полный примерComplete example

ПонятияConcepts

ЗадачиTasks

РуководствоGuidelines

СсылкаReference