Como fazer a manutenção da impressora em um aplicativo de dispositivo UWP

No Windows 8.1, os aplicativos de dispositivo UWP podem executar a manutenção da impressora, como alinhar os cabeçotes de impressão e limpar os bicos. Este tópico usa a versão de C# do exemplo Gerenciamento de trabalho de impressão e manutenção de impressora para demonstrar como a comunicação bidirecional (Bidi) pode ser usada para executar a manutenção desse dispositivo. Para saber mais sobre aplicativos de dispositivo UWP em geral, consulte Conhecer os aplicativos de dispositivo UWP.

A versão de C# do exemplo Gerenciamento de trabalho de impressão e manutenção de impressora demonstra a manutenção da impressora com o arquivo DeviceMaintenance.xaml.cs no projeto DeviceAppForPrinters2. Para trabalhar com Bidi, o exemplo usa a biblioteca de extensão de impressora no projeto PrinterExtensionLibrary. A biblioteca de extensão de impressora fornece uma maneira conveniente de acessar as interfaces de extensão de impressora do driver de impressão v4. Para obter mais informações, consulte Visão geral da biblioteca de extensões de impressora.

Manutenção da impressora

O Windows 8.1 apresenta novas interfaces de extensão de impressora no driver de impressora v4 que você pode usar para implementar a manutenção do dispositivo: IPrinterBidiSetRequestCallback, IPrinterExtensionAsyncOperation e IPrinterQueue2. Essas interfaces possibilitam o envio assíncrono de solicitações Bidi para o monitor de porta, para que possam ser convertidas em comandos específicos do dispositivo e do protocolo e, em seguida, enviadas para a impressora. Para obter mais informações, consulte Manutenção do dispositivo (driver de impressora v4).

Pré-requisitos

Antes de começar:

1. Verifique se a impressora está instalada usando um driver de impressão v4. Para obter mais informações, consulte Desenvolvendo drivers de impressão v4.

2. Obtenha a configuração de seu computador de desenvolvimento. Consulte Introdução para obter informações sobre como baixar as ferramentas e criar uma conta de desenvolvedor.

3. Associar seu aplicativo à loja. Consulte Criar um aplicativo de dispositivo UWP para obter informações sobre isso.

4. Crie metadados de dispositivo para sua impressora que os associem ao seu aplicativo. Consulte Criar metadados do dispositivo para saber mais sobre isso.

5. Crie a interface do usuário para a página principal do seu aplicativo. Todos os aplicativos de dispositivo UWP podem ser iniciados pelo menu Início, em que serão exibidos em tela inteira. Use a experiência de Início para destacar seu produto ou serviços de uma maneira que corresponda à identidade visual e aos recursos específicos de seus dispositivos. Não há restrições especiais sobre o tipo de controles de interface do usuário que ele pode usar. Para começar a usar o design da experiência de tela inteira, consulte os princípios de design da Microsoft Store.

6. Se você estiver escrevendo seu aplicativo com C# ou JavaScript, adicione o projeto PrinterExtensionLibrary à sua solução de aplicativo de dispositivo UWP. Você pode encontrar esse projeto no exemplo Gerenciamento de trabalho de impressão e manutenção de impressora.

Etapa 1: Preparar a solicitação Bidi

As interfaces de manutenção de dispositivo requerem que as solicitações Bidi sejam dados XML na forma de uma cadeia de caracteres. Você pode construir suas solicitações Bidi onde quer que faça sentido em seu aplicativo. Por exemplo, você pode salvar as solicitações Bidi como constantes de cadeia de caracteres ou criá-las dinamicamente com base na entrada de usuário. O exemplo Gerenciamento de trabalho de impressão e manutenção de impressora constrói uma solicitação padrão no método OnNavigatedTo. Para obter mais informações sobre Bidi, consulte Comunicações bidirecionais.

Este exemplo é do método OnNavigatedTo do arquivo DeviceMaintenance.xaml.cs.

string defaultBidiQuery =
    "<bidi:Set xmlns:bidi=\"http://schemas.microsoft.com/windows/2005/03/printing/bidi\">\r\n" +
    "    <Query schema='\\Printer.Maintenance:CleanHead'>\r\n" +
    "        <BIDI_BOOL>false</BIDI_BOOL>\r\n" +
    "    </Query>\r\n" +
    "</bidi:Set>";

Etapa 2: Localizar impressora

Para que seu aplicativo possa enviar comandos para a impressora, primeiro é necessário localizá-la. Para fazer isso, o exemplo Gerenciamento de trabalho de impressão e manutenção de impressora inclui uma classe denominada PrinterEnumeration (no arquivo PrinterEnumeration.cs). Essa classe localiza todas as impressoras associadas ao seu aplicativo por meio de metadados do dispositivo e retorna uma lista de objetos PrinterInfo, que contém os nomes e as IDs de dispositivo para cada impressora.

Este exemplo é do método EnumeratePrinters_Click do arquivo DeviceMaintenance.xaml.cs. Ele mostra como o exemplo usa a classe PrinterEnumeration para obter uma lista de impressoras associadas.

private async void EnumeratePrinters_Click(object sender, RoutedEventArgs e)
{
    try
    {
        rootPage.NotifyUser("Enumerating printers. Please wait", NotifyType.StatusMessage);

        // Retrieve the running app's package family name, and enumerate associated printers.
        string currentPackageFamilyName = Windows.ApplicationModel.Package.Current.Id.FamilyName;

        // Enumerate associated printers.
        PrinterEnumeration pe = new PrinterEnumeration(currentPackageFamilyName);
        List<PrinterInfo> associatedPrinters = await pe.EnumeratePrintersAsync();

        // Update the data binding source on the combo box that displays the list of printers.
        PrinterComboBox.ItemsSource = associatedPrinters;
        if (associatedPrinters.Count > 0)
        {
            PrinterComboBox.SelectedIndex = 0;
            rootPage.NotifyUser(associatedPrinters.Count + " printers enumerated", NotifyType.StatusMessage);
        }
        else
        {
            rootPage.NotifyUser(DisplayStrings.NoPrintersEnumerated, NotifyType.ErrorMessage);
        }
    }
    catch (Exception exception)
    {
        rootPage.NotifyUser("Caught an exception: " + exception.Message, NotifyType.ErrorMessage);
    }
}

Etapa 3: Enviar solicitação Bidi

Para enviar a solicitação Bidi, as interfaces de manutenção do dispositivo requerem uma cadeia de caracteres Bidi e um retorno de chamada. No método SendBidiRequest_Click, o exemplo primeiro usa um objeto PrinterInfo para criar um objeto de contexto de extensão de impressora denominado context. Em seguida, um objeto PrinterBidiSetRequestCallback é criado e um manipulador de eventos é adicionado para manipular o evento OnBidiResponseReceived do retorno de chamada. Finalmente, o método SendBidiSetRequestAsync do contexto da extensão da impressora é usado para enviar a cadeia de caracteres Bidi e o retorno de chamada.

Este exemplo é do método SendBidiRequest_Click do arquivo DeviceMaintenance.xaml.cs.

private void SendBidiRequest_Click(object sender, RoutedEventArgs e)
{
    try
    {
        PrinterInfo queue = (PrinterInfo)PrinterComboBox.SelectedItem;

        // Retrieve a COM IPrinterExtensionContext object, using the static WinRT factory.
        // Then instantiate one "PrinterExtensionContext" object that allows operations on the COM object.
        Object comContext = Windows.Devices.Printers.Extensions.PrintExtensionContext.FromDeviceId(queue.DeviceId);
        PrinterExtensionContext context = new PrinterExtensionContext(comContext);

        // Create an instance of the callback object, and perform an asynchronous 'bidi set' operation.
        PrinterBidiSetRequestCallback callback = new PrinterBidiSetRequestCallback();

        // Add an event handler to the callback object's OnBidiResponseReceived event.
        // The event handler will be invoked once the Bidi response is received.
        callback.OnBidiResponseReceived += OnBidiResponseReceived;

        // Send the Bidi "Set" query asynchronously.
        IPrinterExtensionAsyncOperation operationContext
            = context.Queue.SendBidiSetRequestAsync(BidiQueryInput.Text, callback);

        // Note: The 'operationContext' object can be used to cancel the operation if required.
    }
    catch (Exception exception)
    {
        rootPage.NotifyUser("Caught an exception: " + exception.Message, NotifyType.ErrorMessage);
    }
}

Etapa 4: Receber resposta Bidi

Quando a operação "set" Bidi é concluída, o objeto de retorno de chamada, do tipo PrinterBidiSetRequestCallback, é invocado. Esse retorno de chamada cuida da manipulação de erros da resposta HRESULT e, em seguida, dispara o evento OnBidiResponseReceived, enviando a resposta Bidi por meio dos parâmetros do evento.

Este exemplo mostra a definição de classe PrinterBidiSetRequestCallback no arquivo DeviceMaintenance.xaml.cs.

internal class PrinterBidiSetRequestCallback : IPrinterBidiSetRequestCallback
{
    /// <summary>
    /// This method is invoked when the asynchronous Bidi "Set" operation is completed.
    /// </summary>
    public void Completed(string response, int statusHResult)
    {
        string result;

        if (statusHResult == (int)HRESULT.S_OK)
        {
            result = "The response is \r\n" + response;
        }
        else
        {
            result = "The HRESULT received is: 0x" + statusHResult.ToString("X") + "\r\n" +
                     "No Bidi response was received";
        }

        // Invoke the event handlers when the Bidi response is received.
        OnBidiResponseReceived(null, result);
    }

    /// <summary>
    /// This event will be invoked when the Bidi 'set' response is received.
    /// </summary>
    public event EventHandler<string> OnBidiResponseReceived;
}

A resposta Bidi é então enviada para o método OnBidiResponseReceived, em que o Dispatcher é usado para exibir os resultados no thread da IU.

Este exemplo é do método OnBidiResponseReceived do arquivo DeviceMaintenance.xaml.cs.

internal async void OnBidiResponseReceived(object sender, string bidiResponse)
{
    await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        BidiResponseOutput.Text = bidiResponse;
    });
}

Testando

Para que você possa testar seu aplicativo de dispositivo UWP, ele deve estar vinculado à impressora usando metadados do dispositivo.

Você precisa de uma cópia do pacote de metadados do dispositivo para sua impressora, a fim de adicionar as informações do aplicativo do dispositivo a ele. Se você não tiver metadados de dispositivo, poderá criá-los usando o Assistente de Criação de Metadados de Dispositivo, conforme descrito no tópico Criar metadados de dispositivo para seu aplicativo de dispositivo UWP.

As etapas a seguir criam seu aplicativo e instalam os metadados do dispositivo.

1. Habilite a assinatura para teste.

   1. Inicie o Assistente de Criação de Metadados de Dispositivo em %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, clicando duas vezes DeviceMetadataWizard.exe

   2. No menu Ferramentas, selecione Habilitar Assinatura para Teste.

2. Reinicialize o computador

3. Crie a solução abrindo o arquivo de solução (.sln). Pressione F7 ou vá para Criar->Criar Solução no menu superior depois que o exemplo foi carregado.

4. Desconecte e desinstale a impressora. Esta etapa será requerida para que o Windows leia os metadados de dispositivo atualizados na próxima vez que o dispositivo for detectado.

5. Edite e salve o metadados do dispositivo. Para vincular o aplicativo de dispositivo ao seu dispositivo, você deve associá-lo ao seu dispositivo. Observação: Se você ainda não criou os metadados do dispositivo, consulte Criar metadados de dispositivo para seu aplicativo de dispositivo UWP.

   1. Se o Assistente de Criação de Metadados de Dispositivo ainda não estiver aberto, inicie-o em %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, clicando duas vezes em DeviceMetadataWizard.exe.

   2. Clique em Editar metadados do dispositivo. Isso permitirá que você edite o pacote de metadados do dispositivo existente.

   3. Na caixa de diálogo Abrir, localize o pacote de metadados do dispositivo associado ao seu aplicativo de dispositivo UWP. (Ele tem uma extensão de arquivo devicemetadata-ms.)

   4. Na página Especificar informações do aplicativo de dispositivo UWP, insira as informações do aplicativo da Microsoft Store na caixa Aplicativo de dispositivo UWP. Clique em Importar arquivo de manifesto do aplicativo UWP para inserir automaticamente o Nome do pacote, o Nome do editor e a ID de aplicativo UWP.

   5. Se seu aplicativo estiver registrado para receber notificações de impressora, preencha a caixa Manipuladores de notificação. Em ID do evento, insira o nome do manipulador de eventos de impressão. Em Ativo de Evento, insira o nome do arquivo em que esse código reside.

   6. Quando terminar, clique em Avançar até chegar à página Concluir.

   7. Na página Revisar o pacote de metadados do dispositivo, verifique se todas as configurações estão corretas e marque a caixa de seleção Copiar o pacote de metadados de dispositivo para o repositório de metadados no computador local. Em seguida, clique em Salvar.

6. Reconecte a impressora para que o Windows leia os metadados atualizados do dispositivo quando ele está conectado.

Tópicos relacionados

Manutenção do dispositivo (driver de impressora v4)

Desenvolvendo drivers de impressão v4

Comunicação bidirecional

Introdução aos aplicativos UWP

Criar um aplicativo de dispositivo UWP (guia passo a passo)

Criar metadados de dispositivo para um aplicativo de dispositivo UWP (guia passo a passo)