Работа с уведомлениями о печати в приложении устройства UWP

Статья
02/14/2024

В Windows 8.1 приложения устройств UWP могут реагировать на двунаправленные события связи (Bidi), отправленные из драйвера печати версии 4. В этом разделе представлены уведомления о печати и показано, как версия C# параметров печати и пример уведомлений печати использует фоновую задачу для реагирования на уведомление о печати. Фоновая задача демонстрирует сохранение сведений о уведомлении в локальном хранилище данных приложения, отправку точек и обновление плитки и значка. Дополнительные сведения о приложениях устройств UWP см. в статье "Знакомство с приложениями устройств UWP".

Версия C# параметров печати и пример уведомлений печати демонстрирует фоновую часть приложения (фоновую задачу) в проекте BackgroundTask . Код фоновой задачи находится в файле PrintBackgroundTask.cs . Приложение переднего плана, полноэкранное приложение, которое можно запустить из start, находится в проекте DeviceAppForPrinters . В файле InkLevel.xaml.cs показан один из способов получения сведений о уведомлении из приложения переднего плана. Для работы с уведомлениями о печати в примере используется библиотека расширений принтера в проекте PrinterExtensionLibrary . Библиотека расширений принтера предоставляет удобный способ доступа к интерфейсам расширения принтера драйвера печати версии 4. Дополнительные сведения см. в обзоре библиотеки расширений принтера.

Примеры кода, показанные в этом разделе, основаны на версии C# параметров печати и образца уведомлений о печати. Этот пример также доступен в JavaScript и C++. Обратите внимание, что поскольку C++ может напрямую получить доступ к COM, версия C++ примера не включает проекты библиотеки кода. Скачайте примеры, чтобы просмотреть последние версии кода.

Печать уведомлений

Уведомления о печати позволяют приложению устройства UWP сообщить пользователю важных событий принтера при печати, таких как бумажный джем, открытие двери принтера, низкие уровни рукописного ввода или ошибки принтера вне бумаги. Когда принтер активирует уведомление, системный брокер событий запускает фоновую задачу приложения. Оттуда фоновая задача может сохранить сведения о уведомлении, отправить всплывающее уведомление, обновить плитку, обновить значок или ничего не делать. Сохраняя сведения о уведомлении, приложение может предоставить пользователям возможность понять и устранить проблемы с принтером.

Производители принтеров должны реализовать Bidi и XML-файл DriverEvent в своем драйвере печати версии 4, чтобы использовать уведомления о печати с приложениями устройств UWP. Дополнительные сведения см. в разделе "Двунаправленная связь".

Когда происходит DriverEvent и фоновая задача приложения устройства UWP, приложение имеет несколько вариантов того, как он может продолжаться. Дополнительные сведения о потоке, который приводит к запуску задачи, см. в разделе "Поддержка драйверов для настраиваемого пользовательского интерфейса".

Фоновая задача может выбрать следующее:

Ничего не делать
Сохранение сведений о уведомлении в локальном хранилище данных приложения
Обновление уведомления плитки приложения UWP
Обновление индикатора уведомлений приложения UWP
Отправка всплывающего уведомления приложения UWP

Уведомление плитки или всплывающее уведомление может позволить пользователю удобно запускать приложение переднего плана. При запуске приложения переднего плана он может использовать OnLaunched метод в App.xaml.cs, чтобы проверка, если он был запущен плиткой или всплывающей инструкцией. Если это так, приложение переднего плана может получить доступ к любым сведениям уведомления о печати в локальном хранилище данных приложения.

Необходимые компоненты

Необходимые условия:

Убедитесь, что принтер установлен с помощью драйвера печати версии 4. Дополнительные сведения см. в статье "Разработка драйверов печати версии 4".
Настройте компьютер разработки. Сведения о скачивании средств и создании учетной записи разработчика см. в статье "Начало работы ".
Свяжите приложение с магазином. Сведения об этом см. в статье "Создание приложения устройства UWP".
Создайте метаданные устройства для принтера, который связывает его с приложением. Дополнительные сведения см. в статье "Создание метаданных устройства".
Создайте пользовательский интерфейс для главной страницы приложения. Все приложения устройств UWP можно запустить с начального экрана, где они будут отображаться в полноэкранном режиме. Используйте интерфейс "Пуск", чтобы выделить продукт или службы таким образом, чтобы соответствовать определенным фирменной символике и функциям ваших устройств. Существуют специальные ограничения на тип элементов управления пользовательским интерфейсом, которые он может использовать. Чтобы приступить к разработке полноэкранного интерфейса, ознакомьтесь с принципами проектирования в Microsoft Store.
Если вы пишете приложение с помощью C# или JavaScript, добавьте проекты PrinterExtensionLibrary и DeviceAppForPrintersLibrary в решение приложения устройства UWP. Вы можете найти каждый из этих проектов в параметрах печати и образце уведомлений о печати.

Так как C++ может получить доступ к COM напрямую, приложения C++ не требуют отдельной библиотеки для работы с контекстом устройства принтера на основе COM.

Шаг 1. Регистрация фоновой задачи

Чтобы Windows распознала, что приложение может обрабатывать уведомления о печати, оно должно зарегистрировать расширение фоновых задач для уведомлений о печати. Это расширение объявляется в элементе Extension с набором атрибутов Categorywindows.backgroundTasks и набором EntryPointBackgroundTask.PrintBackgroundTaskатрибутов. Расширение также содержит элемент, указывающий Task на то, что он поддерживает systemEvent типы задач.

Вы можете добавить расширение фоновой задачи печати на вкладке "Объявления" конструктора манифестов в Microsoft Visual Studio. Можно также вручную изменить XML-код манифеста пакета приложения с помощью редактора XML (текста). Щелкните правой кнопкой мыши файл Package.appxmanifest в Обозреватель решений для параметров редактирования.

В этом примере показано расширение фоновой задачи в элементе, как оно отображается в Extension файле манифеста пакета приложения Package.appxmanifest.

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest">
  <Identity Name="Microsoft.SDKSamples.DeviceAppForPrinters.CS" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" Version="1.0.0.0" />
  <Properties>
    <DisplayName>Device App For Printers C# sample</DisplayName>
    <PublisherDisplayName>Microsoft Corporation</PublisherDisplayName>
    <Logo>Assets\storeLogo-sdk.png</Logo>
  </Properties>
  <Prerequisites>
    <OSMinVersion>6.3.0</OSMinVersion>
    <OSMaxVersionTested>6.3.0</OSMaxVersionTested>
  </Prerequisites>
  <Resources>
    <Resource Language="x-generate" />
  </Resources>
  <Applications>
    <Application Id="DeviceAppForPrinters" Executable="$targetnametoken$.exe" EntryPoint="DeviceAppForPrinters.App">
      <VisualElements DisplayName="Device App For Printers C# sample" Logo="Assets\squareTile-sdk.png"
                      SmallLogo="Assets\smallTile-sdk.png" Description="DeviceAppForPrinters C# sample"
                      ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="true">
        <DefaultTile ShowName="allLogos" ShortName="App4PrinterCS" WideLogo="Assets\tile-sdk.png" />
        <SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
      </VisualElements>
      <Extensions>
        <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTask.PrintBackgroundTask">
          <BackgroundTasks>
            <Task Type="systemEvent" />
          </BackgroundTasks>
        </Extension>
        <Extension Category="windows.printTaskSettings" Executable="$targetnametoken$.exe" EntryPoint="DeviceAppForPrinters.App" />
      </Extensions>
    </Application>
  </Applications>
</Package>

Шаг 2. Настройка метаданных устройства

Если вы используете мастер разработки метаданных устройства для связывания приложения с устройством, убедитесь, что на странице сведений о приложении устройства UWP заполните поле обработчиков уведомлений. Это помогает гарантировать, что фоновая задача приложения вызывается во время уведомления о печати.

Пошаговые инструкции по изменению метаданных устройства см. в разделе "Тестирование ".

Шаг 3. Создание пользовательского интерфейса

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

Шаг 4. Создание фоновой задачи

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

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

Сохранение сведений о уведомлении

Фоновая задача не может запускать приложение переднего плана напрямую, только пользователь может: от плитки, всплывающего элемента или запуска. Таким образом, чтобы приложение переднего плана получите доступ к сведениям о уведомлении печати, фоновая задача сохраняет их в локальном хранилище. Дополнительные сведения об использовании локального хранилища см . в кратком руководстве: данные локального приложения.

При активации уведомления о печати Windows запускает фоновую задачу, вызывая его Run метод. Данные уведомления передаются фоновой задаче с помощью параметра метода, который необходимо привести к типу Windows.Devices.Printers.Extensions.PrintNotificationEventDetails. EventData Свойства PrinterName этого объекта содержат имя принтера и сообщение Bidi соответственно.

В этом примере показан метод фоновой задачи Run в файле PrintBackgroundTask.cs , где сведения о уведомлении печати сохраняются в параметрах приложения до вызова методов всплывающего уведомления, плитки и индикатора событий.

public void Run(Windows.ApplicationModel.Background.IBackgroundTaskInstance taskInstance)
{
    // Save notification details to local storage
    PrintNotificationEventDetails details = (PrintNotificationEventDetails)taskInstance.TriggerDetails;
    settings.Values[keyPrinterName] = details.PrinterName;
    settings.Values[keyAsyncUIXML] = details.EventData;

    // Demonstrate possible actions
    ShowToast(details.PrinterName, details.EventData);
    UpdateTile(details.PrinterName, details.EventData);
    UpdateBadge();
}

Обновление плитки

Когда сведения о уведомлении печати отправляются в UpdateTile метод, фоновая задача примера демонстрирует, как отобразить их на плитке. Дополнительные сведения о плитках см. в обзоре уведомлений о плитках и плитках.

В этом примере показан метод фоновой задачи UpdateTile в файле PrintBackgroundTask.cs .

void UpdateTile(string printerName, string bidiMessage)
{
    TileUpdater tileUpdater = TileUpdateManager.CreateTileUpdaterForApplication();
    tileUpdater.Clear();

    XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150Text09);
    XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
    tileTextAttributes[0].InnerText = printerName;
    tileTextAttributes[1].InnerText = bidiMessage;

    TileNotification tileNotification = new TileNotification(tileXml);
    tileNotification.Tag = "tag01";
    tileUpdater.Update(tileNotification);
}

Обновление значка

В этом методе UpdateBadge показано, как использовать класс BadgeNotification для обновления значка. Дополнительные сведения о плитках см. в обзоре значков.

В этом примере показан метод фоновой задачи UpdateBadge в файле PrintBackgroundTask.cs .

void UpdateBadge()
{
    XmlDocument badgeXml = BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeGlyph);
    XmlElement badgeElement = (XmlElement)badgeXml.SelectSingleNode("/badge");
    badgeElement.SetAttribute("value", "error");

    var badgeNotification = new BadgeNotification(badgeXml);
    BadgeUpdateManager.CreateBadgeUpdaterForApplication().Update(badgeNotification);
}

Поднятие тост

Всплывающее уведомление — это временное сообщение пользователю, содержашему релевантную, конфиденциальную информацию о времени и предоставляющую быстрый доступ к связанному содержимому в приложении. Всплывающие уведомления должны просматриваться пользователям как приглашение вернуться в приложение, чтобы следить за чем-то интересующим. Дополнительные сведения см. в обзоре всплывающих уведомлений.

Чтобы включить всплывающие уведомления, приложение должно зарегистрировать его в манифесте пакета приложения. В элементе VisualElements задайте для атрибута ToastCapable значение true.

Важно!

Мы не рекомендуем всегда показывать всплывающее уведомление, особенно для неисдейственных событий. Это может стать раздражающим для пользователей и привести их к отключению всех точек из приложения. Для событий, которые не требуют непосредственного внимания пользователя, мы рекомендуем обновить только плитку и эмблему, а не отображать всплывающее уведомление.

В этом примере показан ToastCapable атрибут в элементе, как он отображается в VisualElements файле манифеста пакета приложения Package.appxmanifest.

<VisualElements DisplayName="Device App For Printers C# sample" Logo="Assets\squareTile-sdk.png"
                SmallLogo="Assets\smallTile-sdk.png" Description="DeviceAppForPrinters C# sample"
                ForegroundText="light" BackgroundColor="#00b2f0" ToastCapable="true">
  <DefaultTile ShowName="allLogos" ShortName="App4PrinterCS" WideLogo="Assets\tile-sdk.png" />
  <SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
</VisualElements>

В этом примере используется ShowToast метод файла PrintBackgroundTask.cs . В нем показано, как создать всплывающее уведомление на основе двух строк, именованных title и body.

void ShowToast(string title, string body)
{
    //
    // Get Toast template
    //
    XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastText02);

    //
    // Pass to app as eventArgs.detail.arguments
    //
    ((XmlElement)toastXml.SelectSingleNode("/toast")).SetAttribute("launch", title);

    //
    // The ToastText02 template has 2 text nodes (a header and a body)
    // Assign title to the first one, and body to the second one
    //
    XmlNodeList textList = toastXml.GetElementsByTagName("text");
    textList[0].AppendChild(toastXml.CreateTextNode(title));
    textList[1].AppendChild(toastXml.CreateTextNode(body));

    //
    // Show the Toast
    //
    ToastNotification toast = new ToastNotification(toastXml);
    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

Шаг 5. Обработка активации

Когда уведомление печати активирует фоновую задачу, приложение можно запустить, нажав всплывающее уведомление или плитку. Если приложение активировано из любого из этих приложений, параметр будет передан в приложение через LaunchActivatedEventArgs.arguments свойство. Дополнительные сведения об активации и жизненном цикле приложений Microsoft Store см. в разделе "Жизненный цикл приложений".

Чтобы определить, активировано ли приложение в одном из этих случаев, обработайте OnLaunched событие и проверьте аргументы событий, передаваемые обработчику событий. Если аргументы события имеют значение NULL, приложение было активировано пользователем из start. Если аргументы события не имеют значения NULL, приложение было запущено из всплывающего элемента или плитки.

В этом примере используется OnLaunched метод файла App.xaml.cs . В нем показано, как обрабатывать активацию из всплывающих элементов или плиток.

protected override async void OnLaunched(LaunchActivatedEventArgs args)
{
    Frame rootFrame = Window.Current.Content as Frame;

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active

    if (rootFrame == null)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        rootFrame = new Frame();
        // Associate the frame with a SuspensionManager key
        SuspensionManager.RegisterFrame(rootFrame, "AppFrame");

        if (args.PreviousExecutionState == ApplicationExecutionState.Terminated)
        {
            // Restore the saved session state only when appropriate
            try
            {
                await SuspensionManager.RestoreAsync();
            }
            catch (SuspensionManagerException)
            {
                //Something went wrong restoring state.
                //Assume there is no state and continue
            }
        }

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;
    }
    if (rootFrame.Content == null || !String.IsNullOrEmpty(args.Arguments))
    {
        // When the navigation stack isn't restored or there are launch arguments
        // indicating an alternate launch (e.g.: via toast or secondary tile),
        // navigate to the appropriate page, configuring the new page by passing required
        // information as a navigation parameter
        if (!rootFrame.Navigate(typeof(MainPage), args.Arguments))
        {
            throw new Exception("Failed to create initial page");
        }
    }
    // Ensure the current window is active
    Window.Current.Activate();
}

Шаг 6. Сведения о уведомлении о доступе

Так как фоновая задача не может напрямую запустить приложение переднего плана, сведения о уведомлении печати должны быть сохранены в параметрах приложения, чтобы приложение переднего плана могли получить к ним доступ. Дополнительные сведения об использовании локального хранилища см . в кратком руководстве: данные локального приложения.

В этом примере показано, как имя принтера и сообщение Bidi извлекаются из параметров приложения в примере параметров печати и уведомлений о печати. Код находится в методе DisplayBackgroundTaskTriggerDetailsфайла InkLevel.xaml.cs . Обратите внимание, что значения keyPrinterName ключевых индексов и keyAsyncUIXMLявляются теми же строковыми константами, которые используются в фоновой задаче, PrintBackgroundTask.cs.

void DisplayBackgroundTaskTriggerDetails()
{
    String outputText = "\r\n";

    try
    {
        string printerName = settings.Values[keyPrinterName].ToString();
        outputText += ("Printer name from background task triggerDetails: " + printerName);
    }
    catch (Exception)
    {
        outputText += ("No printer name retrieved from background task triggerDetails ");
    }

    outputText += "\r\n";
    try
    {
        string asyncUIXML = settings.Values[keyAsyncUIXML].ToString();
        outputText += ("AsyncUI xml from background task triggerDetails: " + asyncUIXML);
    }
    catch (Exception)
    {
        outputText += ("No asyncUI xml retrieved from background task triggerDetails ");
    }

    ToastOutput.Text += outputText;
}

Тестирование

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

Для добавления в него сведений о приложении устройства требуется копия пакета метаданных устройства. Если у вас нет метаданных устройства, его можно создать с помощью мастера создания метаданных устройств, как описано в разделе "Создание метаданных устройства для приложения устройства UWP".

Чтобы использовать мастер разработки метаданных устройств, необходимо установить Microsoft Visual Studio Professional, Microsoft Visual Studio Ultimate или автономный пакет SDK для Windows 8.1, прежде чем выполнить действия, описанные в этом разделе. Установка Microsoft Visual Studio Express для Windows устанавливает версию пакета SDK, которая не включает мастер.

Следующие шаги по созданию приложения и установке метаданных устройства.

Включите тестовую подпись.
1. Запустите мастер разработки метаданных устройства из %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, дважды щелкнув DeviceMetadataWizard.exe
2. В меню "Сервис" выберите "Включить подписывание тестов".
Перезагрузите компьютер.
Создайте решение, открыв файл решения (.sln). Нажмите клавишу F7 или перейдите к решению сборки> из верхнего меню после загрузки примера.
Отключите и удалите принтер. Этот шаг необходим, чтобы Windows считывала обновленные метаданные устройства при следующем обнаружении устройства.
Изменение и сохранение метаданных устройства. Чтобы связать приложение устройства с устройством, необходимо связать приложение устройства с устройством.

Если вы еще не создали метаданные устройства, см. статью "Создание метаданных устройства" для приложения устройства UWP.
1. Если мастер разработки метаданных устройства еще не открыт, запустите его с %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, дважды щелкнув DeviceMetadataWizard.exe.
2. Нажмите кнопку "Изменить метаданные устройства". Это позволит изменить существующий пакет метаданных устройства.
3. В диалоговом окне "Открыть" найдите пакет метаданных устройства, связанный с приложением устройства UWP. (Он имеет расширение файла devicemetadata-ms .)
4. На странице сведений о приложении устройства UWP введите сведения о приложении Microsoft Store в поле приложения устройства UWP. Щелкните импорт файла манифеста приложения UWP, чтобы автоматически ввести имя пакета, имя издателя и идентификатор приложения UWP.
5. Если приложение регистрируется для уведомлений принтера, заполните поле обработчиков уведомлений. Введите имя обработчика событий печати в идентификаторе события. В ресурсе событий введите имя файла, в котором находится этот код.
6. По завершении нажмите кнопку "Далее ", пока не перейдете на страницу "Готово ".
7. На странице "Проверка пакета метаданных устройства" убедитесь, что все параметры правильны и выберите пакет метаданных устройства в хранилище метаданных на локальном компьютере проверка. Нажмите кнопку Сохранить.
Повторно подключите принтер, чтобы Windows считывала обновленные метаданные устройства при подключении устройства.

Устранение неполадок

Проблема: не отображается всплывающее уведомление по умолчанию

Если уведомление о печати по умолчанию не отображается, когда ожидается...

Возможная причина. Проверка подписывания не включена. Дополнительные сведения о включении см. в разделе "Отладка".
Возможная причина: политики домена отключили всплывающие уведомления. Оставьте домен и повторите попытку.
Возможная причина: принтер не реализовал DriverEvents. Убедитесь, что драйвер версии 4 поддерживает Bidi и DriverEvents. Дополнительные сведения см. в разделе "Поддержка драйверов для настраиваемого пользовательского интерфейса".
Возможная причина: компьютер не имеет недавнего задания в очереди принтера. Убедитесь, что значок принтера отображается в правом нижнем углу экрана. В противном случае отправьте другое задание печати.
Возможная причина. Точка входа для фоновой задачи (IBackgroundTask) находится в том же проекте, что и приложение переднего плана. Это не допускается. Отделите совершенно новый класс для обработчика фоновых задач.
Возможные причины. Класс, который является точкой входа для уведомлений в приложении, неправильно указан в манифесте или метаданных устройства, что приводит к сбою приложения в фоновом хосте и не отображает всплывающее уведомление. Проверьте следующее:
- Убедитесь, что точка входа указана правильно на вкладке "Объявления" конструктора манифестов . Он должен быть в виде Namespace.ClassName для C# и C++. Для JavaScript это должен быть относительный путь к файлу .js.
- Приложение JavaScript должно вызывать close() после завершения.
- Класс C# должен реализовать Windows.ApplicationModel.Background.IBackgroundTask и должен иметь открытый метод void Run(Windows.ApplicationModel.Background.IBackgroundTaskInstance taskInstance) .
- Класс C++ должен реализовать Windows::ApplicationModel::Background::IBackgroundTask и должен иметь virtual void Run(Windows::ApplicationModel::Background::IBackgroundTaskInstance^ taskInstance) метод.