Personnaliser le workflow d’impressionCustomize the print workflow

Vue d’ensembleOverview

Les développeurs peuvent personnaliser l’expérience de flux de travail d’impression via l’utilisation d’une application de flux de travail d’impression.Developers can customize the printing workflow experience through the use of a print workflow app. Les applications de flux de travail d’impression sont des applications UWP qui étendent les fonctionnalités des applications de périphériques Microsoft Store (WSDAs). il est donc utile de vous familiariser avec WSDAs avant de continuer.Print workflow apps are UWP apps that expand on the functionality of Microsoft Store devices apps (WSDAs), so it will be helpful to have some familiarity with WSDAs before going further.

Tout comme dans le cas de WSDAs, lorsque l’utilisateur d’une application source choisit d’imprimer un texte et parcourt la boîte de dialogue d’impression, le système vérifie si une application de workflow est associée à cette imprimante.Just as in the case of WSDAs, when the user of a source application elects to print something and navigates through the print dialog, the system checks whether a workflow app is associated with that printer. Si c’est le cas, l’application de flux de travail d’impression démarre (principalement en tant que tâche en arrière-plan ; en savoir plus sur ce qui suit).If it is, the print workflow app launches (primarily as a background task; more on this below). Une application de flux de travail est en mesure de modifier à la fois le ticket d’impression (le document XML qui configure les paramètres de l’imprimante pour la tâche d’impression en cours) et le contenu XPS réel à imprimer.A workflow app is able to alter both the print ticket (the XML document that configures the printer device settings for the current print task) and the actual XPS content to be printed. Il peut éventuellement exposer cette fonctionnalité à l’utilisateur en lançant une interface utilisateur au milieu du processus.It can optionally expose this functionality to the user by launching a UI midway through the process. Après avoir effectué son travail, il transmet le contenu d’impression et le ticket d’impression au pilote.After doing its work, it passes the print content and print ticket on to the driver.

Comme il implique des composants d’arrière-plan et de premier plan, et parce qu’il est associé de façon fonctionnelle à d’autres applications, une application de flux de travail d’impression peut être plus compliquée à implémenter que d’autres catégories d’applications UWP.Because it involves background and foreground components, and because it is functionally coupled with other app(s), a print workflow app can be more complicated to implement than other categories of UWP apps. Nous vous recommandons d’examiner l' exemple d’application de workflow tout en lisant ce guide pour mieux comprendre comment les différentes fonctionnalités peuvent être implémentées.It is recommended that you inspect the Workflow app sample while reading this guide to better understand how the different features can be implemented. Certaines fonctionnalités, telles que les vérifications des erreurs et la gestion de l’interface utilisateur, sont absentes de ce guide pour des raisons de simplicité.Some features, such as various error checks and UI management, are absent from this guide for the sake of simplicity.

Mise en routeGetting started

L’application de flux de travail doit indiquer son point d’entrée au système d’impression afin qu’elle puisse être lancée à l’heure appropriée.The workflow app must indicate its entry point to the print system so that it can be launched at the appropriate time. Pour ce faire, insérez la déclaration suivante dans l' Application/Extensions élément du fichier Package. appxmanifest du projet UWP.This is done by inserting the following declaration in the Application/Extensions element of the UWP project's package.appxmanifest file.

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

Important

Il existe de nombreux scénarios dans lesquels la personnalisation de l’impression ne nécessite pas d’entrée utilisateur.There are many scenarios in which the print customization does not require user input. Pour cette raison, les applications de flux de travail d’impression s’exécutent en tant que tâches en arrière-plan par défaut.For this reason, Print workflow apps run as background tasks by default.

Si une application de workflow est associée à l’application source qui a démarré le travail d’impression (voir la section suivante pour obtenir des instructions à ce propos), le système d’impression examine ses fichiers manifeste pour un point d’entrée de tâche en arrière-plan.If a workflow app is associated with the source application that started the print job (see later section for instructions on this), the print system examines its manifest files for a background task entry point.

Effectuer un travail en arrière-plan sur le ticket d’impressionDo background work on the print ticket

La première chose que fait le système d’impression avec l’application de flux de travail est d’activer sa tâche en arrière-plan (dans ce cas, la WfBackgroundTask classe dans l' WFBackgroundTasks espace de noms).The first thing the print system does with the workflow app is activate its background task (In this case, the WfBackgroundTask class in the WFBackgroundTasks namespace). Dans la méthode de la tâche en arrière-plan Run , vous devez effectuer un cast des détails du déclencheur de la tâche en instance PrintWorkflowTriggerDetails .In the background task's Run method, you should cast the task's trigger details as a PrintWorkflowTriggerDetails instance. Cela fournira les fonctionnalités spéciales pour une tâche d’arrière-plan du flux de travail d’impression.This will provide the special functionality for a print workflow background task. Il expose la propriété PrintWorkflowSession , qui est une instance de PrintWorkFlowBackgroundSession.It exposes the PrintWorkflowSession property, which is an instance of PrintWorkFlowBackgroundSession. Imprimer les classes de session de workflow-à la fois les variétés d’arrière-plan et de premier plan : contrôle les étapes séquentielles de l’application de flux de travail d’impression.Print workflow session classes - both the background and foreground varieties - will control the sequential steps of the print workflow app.

Enregistrez ensuite les méthodes de gestionnaire pour les deux événements déclenchés par cette classe de session.Then register handler methods for the two events that this session class will raise. Vous allez définir ces méthodes ultérieurement.You will define these methods later on.

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();
}

Lorsque la Start méthode est appelée, le gestionnaire de sessions déclenche d’abord l’événement SetupRequested .When the Start method is called, the session manager will raise the SetupRequested event first. Cet événement expose des informations générales sur la tâche d’impression, ainsi que le ticket d’impression.This event exposes general information about the print task, as well as the print ticket. À ce niveau, le ticket d’impression peut être modifié en arrière-plan.At this stage, the print ticket can be edited in the background.

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();

    // ...

Il est important, dans la gestion du SetupRequested , que l’application détermine si un composant de premier plan doit être lancé.Importantly, it is in the handling of the SetupRequested that the app will determine whether to launch a foreground component. Cela peut dépendre d’un paramètre précédemment enregistré dans le stockage local ou d’un événement qui s’est produit lors de la modification du ticket d’impression, ou il peut s’agir d’un paramètre statique de votre application spécifique.This could depend on a setting that was previously saved to local storage, or an event that occurred during the editing of the print ticket, or it may be a static setting of your particular app.

// ...

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();

Effectuer un travail de premier plan sur le travail d’impression (facultatif)Do foreground work on the print job (optional)

Si la méthode SetRequiresUI a été appelée, le système d’impression examinera le fichier manifeste pour le point d’entrée vers l’application de premier plan.If the SetRequiresUI method was called, then the print system will examine the manifest file for the entry point to the foreground application. L' Application/Extensions élément de votre fichier Package. appxmanifest doit contenir les lignes suivantes.The Application/Extensions element of your package.appxmanifest file must have the following lines. Remplacez la valeur de EntryPoint par le nom de l’application de premier plan.Replace the value of EntryPoint with name of the foreground app.

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

Ensuite, le système d’impression appelle la méthode OnActivated pour le point d’entrée de l’application donné.Next, the print system calls the OnActivated method for the given app entry point. Dans la méthode OnActivated de son fichier app.Xaml.cs , l’application de flux de travail doit vérifier le type d’activation pour vérifier qu’il s’agit d’une activation de flux de travail.In the OnActivated method of its App.xaml.cs file, the workflow app should check the activation kind to verify that it is a workflow activation. Si c’est le cas, l’application de flux de travail peut effectuer un cast des arguments d’activation vers un objet PrintWorkflowUIActivatedEventArgs , qui expose un objet PrintWorkflowForegroundSession en tant que propriété.If so, the workflow app can cast the activation arguments to a PrintWorkflowUIActivatedEventArgs object, which exposes a PrintWorkflowForegroundSession object as a property. Cet objet, comme son équivalent d’arrière-plan dans la section précédente, contient des événements déclenchés par le système d’impression et vous pouvez assigner des gestionnaires à ces objets.This object, like its background counterpart in the previous section, contains events that are raised by the print system, and you can assign handlers to these. Dans ce cas, la fonctionnalité de gestion des événements sera implémentée dans une classe distincte appelée WorkflowPage .In this case, the event-handling functionality will be implemented in a separate class called WorkflowPage.

Tout d’abord, dans le fichier app.Xaml.cs :First, in the App.xaml.cs file:

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();
    }
}

Une fois que l’interface utilisateur a attaché des gestionnaires d’événements et que la méthode OnActivated s’est arrêtée, le système d’impression déclenche l’événement SetupRequested à gérer par l’interface utilisateur.Once the UI has attached event handlers and the OnActivated method has exited, the print system will fire the SetupRequested event for the UI to handle. Cet événement fournit les mêmes données que l’événement de configuration de tâche en arrière-plan, y compris les informations sur le travail d’impression et le document de ticket d’impression, mais sans la possibilité de demander le lancement d’une interface utilisateur supplémentaire.This event provides the same data that the background task setup event provided, including the print job info and print ticket document, but without the ability to request the launch of additional UI. Dans le fichier WorkflowPage.Xaml.cs :In the WorkflowPage.xaml.cs file:

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();
    }
}

Ensuite, le système d’impression déclenche l’événement XpsDataAvailable pour l’interface utilisateur.Next, the print system will raise the XpsDataAvailable event for the UI. Dans le gestionnaire de cet événement, l’application de workflow peut accéder à toutes les données disponibles pour l’événement d’installation et peut également lire directement les données XPS, soit en tant que flux d’octets bruts, soit en tant que modèle objet.In the handler for this event, the workflow app can access all of the data available to the setup event and can additionally read the XPS data directly, either as a stream of raw bytes or as an object model. L’accès aux données XPS permet à l’interface utilisateur de fournir des services d’aperçu avant impression et de fournir à l’utilisateur des informations supplémentaires sur les opérations que l’application de flux de travail exécutera sur les données.Access to the XPS data allows the UI to provide print preview services and to provide additional information to the user about the operations that the workflow app will execute on the data.

Dans le cadre de ce gestionnaire d’événements, l’application de flux de travail doit acquérir un objet report s’il continue à interagir avec l’utilisateur.As part of this event handler, the workflow app must acquire a deferral object if it will continue to interact with the user. Sans Report, le système d’impression considère que la tâche d’interface utilisateur se termine lorsque le gestionnaire d’événements XpsDataAvailable s’arrête ou lorsqu’il appelle une méthode Async.Without a deferral, the print system will consider the UI task complete when the XpsDataAvailable event handler exits or when it calls an async method. Lorsque l’application a rassemblé toutes les informations requises de l’interaction de l’utilisateur avec l’interface utilisateur, elle doit effectuer le report pour que le système d’impression puisse avancer.When the app has gathered all required information from the user's interaction with the UI, it should complete the deferral so that the print system can then advance.

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();
}

En outre, l’instance PrintWorkflowSubmittedOperation exposée par les arguments d’événement donne la possibilité d’annuler le travail d’impression ou d’indiquer que le travail a réussi, mais qu’aucun travail d’impression de sortie n’est nécessaire.Additionally, the PrintWorkflowSubmittedOperation instance exposed by the event args provides the option to cancel the print job or to indicate that the job is successful but that no output print job will be needed. Pour ce faire, appelez la méthode Complete avec une valeur PrintWorkflowSubmittedStatus .This is done by calling the Complete method with a PrintWorkflowSubmittedStatus value.

Notes

Si l’application de workflow annule le travail d’impression, il est vivement recommandé de fournir une notification Toast indiquant la raison pour laquelle le travail a été annulé.If the workflow app cancels the print job, it is highly recommended that it provide a toast notification indicating why the job was cancelled.

Effectuer le travail d’arrière-plan final sur le contenu d’impressionDo final background work on the print content

Une fois que l’interface utilisateur a terminé le report dans l’événement PrintTaskXpsDataAvailable (ou si l’étape de l’interface utilisateur a été contournée), le système d’impression déclenche l’événement soumis pour la tâche en arrière-plan.Once the UI has completed the deferral in the PrintTaskXpsDataAvailable event (or if the UI step was bypassed), the print system will fire the Submitted event for the background task. Dans le gestionnaire de cet événement, l’application de workflow peut accéder à toutes les données fournies par l’événement XpsDataAvailable .In the handler for this event, the workflow app can get access to all of the same data provided by the XpsDataAvailable event. Toutefois, contrairement à l’un des événements précédents, l' envoi fournit également un accès en écriture au contenu du travail d’impression final via une instance PrintWorkflowTarget .However, unlike any of the previous events, Submitted also provides write access to the final print job content through a PrintWorkflowTarget instance.

L’objet qui est utilisé pour spouler les données pour l’impression finale varie selon que les données sources sont accessibles en tant que flux d’octets bruts ou en tant que modèle objet XPS.The object that is used to spool the data for final printing depends on whether the source data is accessed as a raw byte stream or as the XPS object model. Lorsque l’application de workflow accède aux données sources via un flux d’octets, un flux d’octets de sortie est fourni pour écrire les données finales du travail dans.When the workflow app accesses the source data through a byte stream, an output byte stream is provided to write the final job data to. Lorsque l’application de workflow accède aux données sources via le modèle objet, un enregistreur de documents est fourni pour écrire des objets dans le travail de sortie.When the workflow app accesses the source data through the object model, a document writer is provided to write objects to the output job. Dans les deux cas, l’application de flux de travail doit lire toutes les données sources, modifier les données requises et écrire les données modifiées dans la cible de sortie.In either case, the workflow app should read all of the source data, modify any data required, and write the modified data to the output target.

Lorsque la tâche en arrière-plan termine l’écriture des données, elle doit appeler Complete sur l’objet PrintWorkflowSubmittedOperation correspondant.When the background task finishes writing the data, it should call Complete on the corresponding PrintWorkflowSubmittedOperation object. Une fois que l’application de workflow a terminé cette étape et que le gestionnaire d’événements soumis se termine, la session de workflow est fermée et l’utilisateur peut surveiller l’état du travail d’impression final à l’aide des boîtes de dialogue d’impression standard.Once the workflow app completes this step and the Submitted event handler exits, the workflow session is closed and the user can monitor the status of the final print job through the standard print dialogs.

Dernières étapesFinal steps

Inscrire l’application de flux de travail d’impression sur l’imprimanteRegister the print workflow app to the printer

Votre application de flux de travail est associée à une imprimante utilisant le même type d’envoi de fichier de métadonnées que pour WSDAs.Your workflow app is associated with a printer using the same type of metadata file submission as for WSDAs. En fait, une seule application UWP peut agir à la fois comme une application de flux de travail et un WSDA qui fournit des fonctionnalités d’impression des paramètres de tâche.In fact, a single UWP application can act as both a workflow app and a WSDA that provides print task settings functionality. Suivez les étapes WSDA correspondantes pour créer l’Association de métadonnées.Follow the corresponding WSDA steps for creating the metadata association.

La différence réside dans le fait que lorsque les WSDAs sont automatiquement activés pour l’utilisateur (l’application est toujours lancée lorsque cet utilisateur imprime sur l’appareil associé), les applications de flux de travail ne le sont pas.The difference is that while WSDAs are automatically activated for the user (the app will always launch when that user prints on the associated device), workflow apps are not. Elles ont une stratégie distincte qui doit être définie.They have a separate policy that must be set.

Définir la stratégie de l’application de workflowSet the workflow app's policy

La stratégie d’application de workflow est définie par les commandes PowerShell sur l’appareil qui doit exécuter l’application de Workflow.The workflow app policy is set by Powershell commands on the device that is to run the workflow app. Les commandes Set-Printer, Add-Printer (port existant) et Add-Printer (nouveau port WSD) sont modifiées pour permettre la définition des stratégies de Workflow.The Set-Printer, Add-Printer (existing port) and Add-Printer (new WSD port) commands will be modified to allow Workflow policies to be set.

  • Disabled: Les applications de flux de travail ne sont pas activées.Disabled: Workflow apps will not be activated.
  • Uninitialized: Les applications de workflow sont activées si le workflow DCA est installé dans le système.Uninitialized: Workflow apps will be activated if the Workflow DCA is installed in the system. Si l’application n’est pas installée, l’impression continuera.If the app is not installed, printing will still proceed.
  • Enabled: Le contrat de workflow sera activé si le processus DCA de workflow est installé dans le système.Enabled: Workflow contract will be activated if the Workflow DCA is installed in the system. Si l’application n’est pas installée, l’impression échoue.If the app is not installed, printing will fail.

La commande suivante rend l’application de flux de travail obligatoire sur l’imprimante spécifiée.The following command makes the workflow app required on the specified printer.

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

Un utilisateur local peut exécuter cette stratégie sur une imprimante locale, ou, pour l’implémentation d’entreprise, l’administrateur de l’imprimante peut exécuter cette stratégie sur le serveur d’impression.A local user can run this policy on a local printer, or, for enterprise implementation, the printer administrator can run this policy on the Print Server. La stratégie est alors synchronisée avec toutes les connexions clientes.The policy will then be synchronized to all client connections. L’administrateur de l’imprimante peut utiliser cette stratégie chaque fois qu’une nouvelle imprimante est ajoutée.The printer admin can use this policy whenever a new printer is added.

Voir aussiSee also

Exemple d’application de workflowWorkflow app sample

Espace de noms Windows. Graphics. Printing. WorkflowWindows.Graphics.Printing.Workflow namespace