Personalizar o fluxo de trabalho de impressão

Crie experiências personalizadas de fluxo de trabalho de impressão através da utilização de uma aplicação de fluxo de trabalho de impressão.

Visão geral

Os aplicativos de fluxo de trabalho de impressão são aplicativos UWP que expandem a funcionalidade de aplicativos de dispositivos da Microsoft Store (WSDAs), portanto, será útil ter alguma familiaridade com WSDAs antes de ir mais longe.

Assim como no caso dos WSDAs, quando o usuário de um aplicativo de origem opta por imprimir algo e navega pela caixa de diálogo de impressão, o sistema verifica se um aplicativo de fluxo de trabalho está associado a essa impressora. Se estiver, o aplicativo de fluxo de trabalho de impressão será iniciado (principalmente como uma tarefa em segundo plano; mais sobre isso abaixo). Um aplicativo de fluxo de trabalho é capaz de alterar o tíquete de impressão (o documento XML que define as configurações do dispositivo de impressora para a tarefa de impressão atual) e o conteúdo XPS real a ser impresso. Opcionalmente, pode expor esta funcionalidade ao utilizador, lançando uma interface de utilizador a meio do processo. Depois de fazer o seu trabalho, passa o conteúdo impresso e o bilhete impresso para o motorista.

Como envolve componentes em segundo plano e em primeiro plano, e porque está funcionalmente acoplado a outro(s) aplicativo(s), um aplicativo de fluxo de trabalho de impressão pode ser mais complicado de implementar do que outras categorias de aplicativos UWP. É recomendável que inspecione o aplicativo de amostra Workflow enquanto lê este guia para entender melhor como os diferentes recursos podem ser implementados. Alguns recursos, como várias verificações de erros e gerenciamento de interface do usuário, estão ausentes deste guia por uma questão de simplicidade.

Como Começar

O aplicativo de fluxo de trabalho deve indicar seu ponto de entrada no sistema de impressão para que ele possa ser iniciado no momento apropriado. Isso é feito inserindo a seguinte declaração no elemento Application/Extensions do package.appxmanifest do projeto UWP em.

<uap:Extension Category="windows.printWorkflowBackgroundTask"  
    EntryPoint="WFBackgroundTasks.WfBackgroundTask" />

Se um aplicativo de fluxo de trabalho estiver associado ao aplicativo de origem que iniciou o trabalho de impressão (consulte a seção posterior para obter instruções sobre isso), o sistema de impressão examinará seus arquivos de manifesto em busca de um ponto de entrada de tarefa em segundo plano.

Efetue um trabalho de preparação no ticket de impressão

A primeira coisa que o sistema de impressão faz com o aplicativo de fluxo de trabalho é ativar sua tarefa em segundo plano (neste caso, a classe WfBackgroundTask no namespace WFBackgroundTasks). No método Run da tarefa em segundo plano, deve converter os detalhes do gatilho da tarefa em uma instância de PrintWorkflowTriggerDetails. Isso fornecerá a funcionalidade especial para uma tarefa em segundo plano do fluxo de trabalho de impressão. Ele expõe a propriedade PrintWorkflowSession, que é uma instância de PrintWorkFlowBackgroundSession. As classes de sessão do fluxo de trabalho de impressão - as variedades de plano de fundo e primeiro plano - controlarão as etapas sequenciais do aplicativo de fluxo de trabalho de impressão.

Em seguida, registre métodos de manipulador para os dois eventos que essa classe de sessão gerará. Você definirá esses métodos mais tarde.

public void Run(IBackgroundTaskInstance taskInstance) {
    // Take out a deferral here and complete once all the callbacks are done
    runDeferral = taskInstance.GetDeferral();

    // Associate a cancellation handler with the background task.
    taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);

    // cast the task's trigger details as PrintWorkflowTriggerDetails
    PrintWorkflowTriggerDetails workflowTriggerDetails = taskInstance.TriggerDetails as PrintWorkflowTriggerDetails;

    // Get the session manager, which is unique to this print job
    PrintWorkflowBackgroundSession sessionManager = workflowTriggerDetails.PrintWorkflowSession;

    // add the event handler callback routines
    sessionManager.SetupRequested += OnSetupRequested;
    sessionManager.Submitted += OnXpsOMPrintSubmitted;

    // Allow the event source to start
    // This call blocks until all of the workflow callbacks complete
    sessionManager.Start();
}

Quando o método Start é chamado, o gestor de sessão acionará primeiro o evento SetupRequested. Este evento expõe informações gerais sobre a tarefa de impressão, bem como o bilhete de impressão. Nesta fase, o bilhete impresso pode ser editado em segundo plano.

private void OnSetupRequested(PrintWorkflowBackgroundSession sessionManager, PrintWorkflowBackgroundSetupRequestedEventArgs printTaskSetupArgs) {
    // Take out a deferral here and complete once all the callbacks are done
    Deferral setupRequestedDeferral = printTaskSetupArgs.GetDeferral();

    // Get general information about the source application, print job title, and session ID
    string sourceApplicationName = printTaskSetupArgs.Configuration.SourceAppDisplayName;
    string jobTitle = printTaskSetupArgs.Configuration.JobTitle;
    string sessionId = printTaskSetupArgs.Configuration.SessionId;

    // edit the print ticket
    WorkflowPrintTicket printTicket = printTaskSetupArgs.GetUserPrintTicketAsync();

    // ...

Importante, é na gestão do SetupRequested que o aplicativo determinará se deve iniciar um componente em primeiro plano. Isso pode depender de uma configuração que foi salva anteriormente no armazenamento local ou de um evento que ocorreu durante a edição do tíquete de impressão, ou pode ser uma configuração estática do seu aplicativo específico.

// ...

if (UIrequested) {
    printTaskSetupArgs.SetRequiresUI();

    // Any data that is to be passed to the foreground task must be stored the app's local storage.
    // It should be prefixed with the sourceApplicationName string and the SessionId string, so that
    // it can be identified as pertaining to this workflow app session.
}

// Complete the deferral taken out at the start of OnSetupRequested
setupRequestedDeferral.Complete();

Fazer trabalho em primeiro plano no trabalho de impressão (opcional)

Se o método SetRequiresUI foi chamado, o sistema de impressão examinará o ficheiro de manifesto para encontrar o ponto de entrada da aplicação em primeiro plano. O elemento do arquivo de package.appxmanifest do deve ter as seguintes linhas. Substitua o valor de EntryPoint pelo nome do aplicativo em primeiro plano.

<uap:Extension Category="windows.printWorkflowForegroundTask"  
    EntryPoint="MyWorkFlowForegroundApp.App" />

Em seguida, o sistema de impressão chama o método OnActivated para o ponto de entrada do aplicativo determinado. No método OnActivated do seu arquivo App.xaml.cs, o aplicativo de fluxo de trabalho deve verificar o tipo de ativação para assegurar que é uma ativação de fluxo de trabalho. Nesse caso, o aplicativo de fluxo de trabalho pode converter os argumentos de ativação em um objeto PrintWorkflowUIActivatedEventArgs, que expõe um objeto PrintWorkflowForegroundSession como uma propriedade. Esse objeto, como sua contraparte em segundo plano na seção anterior, contém eventos que são gerados pelo sistema de impressão e você pode atribuir manipuladores a eles. Nesse caso, a funcionalidade de manipulação de eventos será implementada em uma classe separada chamada WorkflowPage.

Primeiro, no arquivo App.xaml.cs:

protected override void OnActivated(IActivatedEventArgs args){

    if (args.Kind == ActivationKind.PrintWorkflowForegroundTask) {

        // the app should instantiate a new UI view so that it can properly handle the case when
        // several print jobs are active at the same time.
        Frame rootFrame = new Frame();
        if (null == Window.Current.Content)
        {
            rootFrame.Navigate(typeof(WorkflowPage));
            Window.Current.Content = rootFrame;
        }

        // Get the main page
        WorkflowPage workflowPage = (WorkflowPage)rootFrame.Content;

        // Make sure the page knows it's handling a foreground task activation
        workflowPage.LaunchType = WorkflowPage.WorkflowPageLaunchType.ForegroundTask;

        // Get the activation arguments
        PrintWorkflowUIActivatedEventArgs printTaskUIEventArgs = args as PrintWorkflowUIActivatedEventArgs;

        // Get the session manager
        PrintWorkflowForegroundSession taskSessionManager = printTaskUIEventArgs.PrintWorkflowSession;

        // Add the callback handlers - these methods are in the workflowPage class
        taskSessionManager.SetupRequested += workflowPage.OnSetupRequested;
        taskSessionManager.XpsDataAvailable += workflowPage.OnXpsDataAvailable;

        // start raising the print workflow events
        taskSessionManager.Start();
    }
}

Depois de a interface do utilizador ter anexado os manipuladores de eventos e o método OnActivated ter terminado, o sistema de impressão irá acionar o evento SetupRequested para que a interface do utilizador o processe. Esse evento disponibiliza os mesmos dados que o evento de tarefa em segundo plano fornecia, incluindo as informações do trabalho de impressão e o bilhete de impressão, mas sem a possibilidade de solicitar a abertura de uma interface adicional para o utilizador. No arquivo WorkflowPage.xaml.cs:

internal void OnSetupRequested(PrintWorkflowForegroundSession sessionManager, PrintWorkflowForegroundSetupRequestedEventArgs printTaskSetupArgs) {
    // If anything asynchronous is going to be done, you need to take out a deferral here,
    // since otherwise the next callback happens once this one exits, which may be premature
    Deferral setupRequestedDeferral = printTaskSetupArgs.GetDeferral();

    // Get information about the source application, print job title, and session ID
    string sourceApplicationName = printTaskSetupArgs.Configuration.SourceAppDisplayName;
    string jobTitle = printTaskSetupArgs.Configuration.JobTitle;
    string sessionId = printTaskSetupArgs.Configuration.SessionId;
    // the following string should be used when storing data that pertains to this workflow session
    // (such as user input data that is meant to change the print content later on)
    string localStorageVariablePrefix = string.Format("{0}::{1}::", sourceApplicationName, sessionID);

    try
    {
        // receive and store user input
        // ...
    }
    catch (Exception ex)
    {
        string errorMessage = ex.Message;
        Debug.WriteLine(errorMessage);
    }
    finally
    {
        // Complete the deferral taken out at the start of OnSetupRequested
        setupRequestedDeferral.Complete();
    }
}

Em seguida, o sistema de impressão acionará o evento XpsDataAvailable para a interface do usuário. No manipulador desse evento, o aplicativo de fluxo de trabalho pode acessar todos os dados disponíveis para o evento de instalação e, adicionalmente, ler os dados XPS diretamente, como um fluxo de bytes brutos ou como um modelo de objeto. O acesso aos dados XPS permite que a interface do usuário forneça serviços de visualização de impressão e forneça informações adicionais ao usuário sobre as operações que o aplicativo de fluxo de trabalho executará nos dados.

Como parte desse manipulador de eventos, o aplicativo de fluxo de trabalho deve adquirir um objeto de adiamento se continuar a interagir com o usuário. Sem um adiamento, o sistema de impressão considerará a tarefa da interface do usuário concluída quando o manipulador de eventos XpsDataAvailable for encerrado ou quando chamar um método assíncrono. Quando a aplicação tiver reunido todas as informações necessárias da interação do utilizador com a interface, deverá concluir o adiamento para que o sistema de impressão possa avançar.

internal async void OnXpsDataAvailable(PrintWorkflowForegroundSession sessionManager, PrintWorkflowXpsDataAvailableEventArgs printTaskXpsAvailableEventArgs)
{
    // Take out a deferral
    Deferral xpsDataAvailableDeferral = printTaskXpsAvailableEventArgs.GetDeferral();

    SpoolStreamContent xpsStream = printTaskXpsAvailableEventArgs.Operation.XpsContent.GetSourceSpoolDataAsStreamContent();

    IInputStream inputStream = xpsStream.GetInputSpoolStream();

    using (var inputReader = new Windows.Storage.Streams.DataReader(inputStream))
    {
        // Read the XPS data from input stream
        byte[] xpsData = new byte[inputReader.UnconsumedBufferLength];
        while (inputReader.UnconsumedBufferLength > 0)
        {
            inputReader.ReadBytes(xpsData);
            // Do something with the XPS data, e.g. preview
            // ...
        }
    }

    // Complete the deferral taken out at the start of this method
    xpsDataAvailableDeferral.Complete();
}

Além disso, a instância PrintWorkflowSubmittedOperation exposta pelo evento args fornece a opção para cancelar o trabalho de impressão ou para indicar que o trabalho foi bem-sucedido, mas que nenhum trabalho de impressão de saída será necessário. Isso é feito chamando o método Complete com um valor PrintWorkflowSubmittedStatus.

Fazer o trabalho final de fundo no conteúdo de impressão

Depois que a interface do usuário tiver concluído o adiamento no evento PrintTaskXpsDataAvailable (ou se a etapa da interface do usuário tiver sido ignorada), o sistema de impressão acionará o evento Submitted para a tarefa em segundo plano. No manipulador para esse evento, o aplicativo de fluxo de trabalho pode obter acesso a todos os mesmos dados fornecidos pelo evento XpsDataAvailable. No entanto, ao contrário de qualquer um dos eventos anteriores, Enviado também fornece gravação acesso ao conteúdo final do trabalho de impressão por meio de uma instância PrintWorkflowTarget .

O objeto usado para armazenar os dados para impressão final depende se os dados de origem são acessados como um fluxo de bytes brutos ou como o modelo de objeto XPS. Quando a aplicação de processos de trabalho acede aos dados de origem por meio de um fluxo de bytes, é fornecido um fluxo de bytes de saída para escrever os dados finais do trabalho. Quando o aplicativo de fluxo de trabalho acessa os dados de origem por meio do modelo de objeto, um gravador de documentos é fornecido para gravar objetos no trabalho de saída. Em ambos os casos, o aplicativo de fluxo de trabalho deve ler todos os dados de origem, modificar todos os dados necessários e gravar os dados modificados no destino de saída.

Quando a tarefa em segundo plano terminar de gravar os dados, deverá chamar Concluído no objeto PrintWorkflowSubmittedOperation correspondente. Depois que o aplicativo de fluxo de trabalho concluir essa etapa e o manipulador de eventos Enviado for encerrado, a sessão de fluxo de trabalho será fechada e o usuário poderá monitorar o status do trabalho de impressão final por meio das caixas de diálogo de impressão padrão.

Etapas finais

Registar a aplicação de fluxo de trabalho de impressão na impressora

Seu aplicativo de fluxo de trabalho está associado a uma impressora usando o mesmo tipo de envio de arquivo de metadados que para WSDAs. Na verdade, um único aplicativo UWP pode atuar como um aplicativo de fluxo de trabalho e um WSDA que fornece funcionalidade de configurações de tarefas de impressão. Siga as etapas correspondentes do WSDA para criar a associação de metadados.

A diferença é que, enquanto os WSDAs são ativados automaticamente para o utilizador (a aplicação será sempre iniciada quando esse utilizador imprimir no dispositivo associado), as aplicações de fluxo de trabalho não são. Eles têm uma política separada que deve ser definida.

Definir a política do aplicativo de fluxo de trabalho

A política do aplicativo de fluxo de trabalho é definida pelos comandos do Powershell no dispositivo que executará o aplicativo de fluxo de trabalho. Os comandos Set-Printer, Add-Printer (porta existente) e Add-Printer (nova porta WSD) serão modificados para permitir que as políticas de Fluxo de Trabalho sejam definidas.

• Disabled: Os aplicativos de fluxo de trabalho não serão ativados.
• Uninitialized: Os aplicativos de fluxo de trabalho serão ativados se o DCA do fluxo de trabalho estiver instalado no sistema. Se o aplicativo não estiver instalado, a impressão ainda continuará.
• Enabled: O contrato de fluxo de trabalho será ativado se o DCA do fluxo de trabalho estiver instalado no sistema. Se o aplicativo não estiver instalado, a impressão falhará.

O comando a seguir torna o aplicativo de fluxo de trabalho necessário na impressora especificada.

Set-Printer –Name "Microsoft XPS Document Writer" -WorkflowPolicy Enabled

Um utilizador local pode executar esta política numa impressora local ou, para implementação empresarial, o administrador da impressora pode executar esta política no Servidor de Impressão. A política será então sincronizada com todas as conexões de cliente. O administrador da impressora pode usar essa política sempre que uma nova impressora for adicionada.

Ver também

Exemplo de aplicativo de fluxo de trabalho

Namespace Windows.Graphics.Printing.Workflow