Anpassen des Druck-WorkflowsCustomize the print workflow

ÜbersichtOverview

Entwickler können den Druck-Workflow durch die Verwendung einer Druck-Workflow-App individuell anpassen.Developers can customize the printing workflow experience through the use of a print workflow app. Druck-Workflow-Apps sind UWP-Apps, die die Funktionalität von Microsoft Store Apps (WSDAs) erweitern. Daher ist es hilfreich, sich mit WSDAs vertraut zu machen.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.

Ähnlich wie bei WSDAs prüft das System, ob eine Workflow-App mit dem Drucker verknüpft ist, wenn der Benutzer einer Quellanwendung etwas ausdruckt und durch den Druckdialog navigiert.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. Ist dies der Fall, startet die Druck-Workflow-App (hauptsächlich als Hintergrundaufgabe; mehr dazu weiter unten).If it is, the print workflow app launches (primarily as a background task; more on this below). Eine Workflow-App ist in der Lage, sowohl das Druckticket (das XML-Dokument, das die Druckereinstellungen für den aktuellen Druckauftrag konfiguriert) als auch den tatsächlich zu druckenden XPS-Inhalt zu ändern.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. Diese Funktionalität kann optional dem Benutzer zur Verfügung gestellt werden, indem im Prozess eine Benutzeroberfläche gestartet wird.It can optionally expose this functionality to the user by launching a UI midway through the process. Nach ihrer Arbeit gibt sie den Druckinhalt und das Druckticket an den Treiber weiter.After doing its work, it passes the print content and print ticket on to the driver.

Da es sich um Hintergrund- und Vordergrundkomponenten handelt und der Prozess funktional mit anderen Apps gekoppelt ist, kann eine Druck-Workflow-App für den Druck komplizierter zu implementieren sein als andere Kategorien von UWP-Apps.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. Es wird empfohlen, sich das Workflow-App-Beispiel anzusehen, während Sie dieses Handbuch lesen, um besser zu verstehen, wie die verschiedenen Funktionen implementiert werden können.It is recommended that you inspect the Workflow app sample while reading this guide to better understand how the different features can be implemented. Einige Funktionen, wie z. B. verschiedene Fehlerprüfungen und die Verwaltung der Benutzeroberfläche, fehlen zur Vereinfachung in diesem Handbuch.Some features, such as various error checks and UI management, are absent from this guide for the sake of simplicity.

Erste SchritteGetting started

Die Workflow-App muss dem Drucksystem den Einstiegspunkt der Workflow-App angeben, damit sie zum richtigen Zeitpunkt gestartet werden kann.The workflow app must indicate its entry point to the print system so that it can be launched at the appropriate time. Dies geschieht durch Einfügen der folgenden Deklaration in das Application/Extensions-Element der package.appxmanifest-Datei des UWP-Projekts.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" />

Wichtig

Es gibt viele Szenarien, in denen das Anpassen des Druck keine Benutzereingaben erfordert.There are many scenarios in which the print customization does not require user input. Aus diesem Grund werden standardmäßig Workflow-Apps für den Druck als Hintergrundaufgaben ausgeführt.For this reason, Print workflow apps run as background tasks by default.

Wenn eine Workflow-App mit der Quellanwendung verknüpft ist, die den Druckauftrag gestartet hat (siehe dazu weiter unten), prüft das Drucksystem seine Manifestdateien auf einen Einstiegspunkt für die Hintergrundaufgabe.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.

Hintergrundarbeiten am Druckticket durchführenDo background work on the print ticket

Das erste, was das Drucksystem mit der Workflow-App macht, ist die Aktivierung der Hintergrundaufgabe (in diesem Fall die Klasse WfBackgroundTask im Namenspace WFBackgroundTasks).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). In der Run-Methode der Hintergrundaufgabe sollten Sie die Trigger-Details des als PrintWorkflowTriggerDetails-Instanz definieren.In the background task's Run method, you should cast the task's trigger details as a PrintWorkflowTriggerDetails instance. Damit steht Ihnen die spezielle Funktionalität für eine Hintergrundaufgabe eines Druck-Workflows zur Verfügung.This will provide the special functionality for a print workflow background task. Sie stellt die PrintWorkflowSession-Eigenschaft bereit, die eine Instanz von PrintWorkFlowBackgroundSession ist.It exposes the PrintWorkflowSession property, which is an instance of PrintWorkFlowBackgroundSession. Die Session-Klassen des Druck-Workflows – sowohl die Varianten für den Hintergrund als auch für den Vordergrund – steuern die Ablaufschritte der Druck-Workflow-App.Print workflow session classes - both the background and foreground varieties - will control the sequential steps of the print workflow app.

Registrieren Sie dann Handler-Methoden für die beiden Ereignisse, die diese Session-Klasse auslösen wird.Then register handler methods for the two events that this session class will raise. Diese Methoden werden Sie später definieren.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();
}

Wenn die Start-Methode aufgerufen wird, löst der Sitzungsmanager das Ereignis SetupRequested zuerst aus.When the Start method is called, the session manager will raise the SetupRequested event first. Dieses Ereignis zeigt allgemeine Informationen über den Druckauftrag sowie das Druckticket an.This event exposes general information about the print task, as well as the print ticket. In dieser Phase kann das Druckticket im Hintergrund bearbeitet werden.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();

    // ...

Wichtig ist, dass die App bei der Verarbeitung von SetupRequested bestimmt, ob sie eine Vordergrundkomponente startet.Importantly, it is in the handling of the SetupRequested that the app will determine whether to launch a foreground component. Dies kann von einer Einstellung abhängen, die zuvor lokal gespeichert wurde, oder von einem Ereignis, das während der Bearbeitung des Drucktickets aufgetreten ist, oder von einer statischen Einstellung Ihrer speziellen App.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();
}

Vordergrundarbeit für den Druckjob verarbeiten (optional)Do foreground work on the print job (optional)

Wurde die Methode SetRequiresUI aufgerufen, dann überprüft das Drucksystem die Manifest-Datei für den Einstiegspunkt in die Vordergrund-Anwendung.If the SetRequiresUI method was called, then the print system will examine the manifest file for the entry point to the foreground application. Das Application/Extensions-Element der Datei package.appxmanifest muss die folgenden Zeilen haben.The Application/Extensions element of your package.appxmanifest file must have the following lines. Ersetzen Sie den Wert von EntryPoint durch den Namen der Vordergrund-App.Replace the value of EntryPoint with name of the foreground app.

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

Als nächstes ruft das Drucksystem die OnActivated-Methode für den angegebenen App-Einsprungspunkt auf.Next, the print system calls the OnActivated method for the given app entry point. In der OnActivated-Methode ihrer App. xaml.cs-Datei sollte die Workflow-Anwendung die Aktivierungsart prüfen, um zu überprüfen, ob es sich um eine Workflow-Aktivierung handelt.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. Wenn ja, kann die Workflow-Anwendung die Aktivierungsargumente in ein PrintWorkflowUIActivatedEventArgs-Objekt umwandeln, das ein PrintWorkflowForegroundSession-Objekt als Eigenschaft ausgibt.If so, the workflow app can cast the activation arguments to a PrintWorkflowUIActivatedEventArgs object, which exposes a PrintWorkflowForegroundSession object as a property. Dieses Objekt enthält, wie sein Gegenstück im vorherigen Abschnitt, Ereignisse, die vom Drucksystem ausgelöst werden, und Sie können diesen Handler zuordnen.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. In diesem Fall wird die Ereignisbehandlungsfunktionalität in einer eigenen Klasse namens WorkflowPage implementiert.In this case, the event-handling functionality will be implemented in a separate class called WorkflowPage.

Zuerst in der Datei 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();
    }
}

Sobald das UI-Ereignis-Handler angehängt und die OnActivated-Methode beendet hat, löst das Drucksystem das SetupRequested-Ereignis für das zu behandelnde UI aus.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. Dieses Ereignis liefert die gleichen Daten wie das Setup-Ereignis der Hintergrundaufgabe, einschließlich der Druckauftragsinfo und des Druckticketdokuments, jedoch ohne die Möglichkeit, den Start eine zusätzlichen UIs anzufordern.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. In der Datei 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();
    }
}

Als nächstes wird das Drucksystem das XpsDataAvailable-Ereignis für das UI auslösen.Next, the print system will raise the XpsDataAvailable event for the UI. Im Handler für dieses Ereignis kann die Workflow-App auf alle dem Setup-Ereignis zur Verfügung stehenden Daten zugreifen und zusätzlich die XPS-Daten direkt lesen, entweder als Raw-Byte-Strom oder als Objektmodell.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. Der Zugriff auf die XPS-Daten ermöglicht es dem UI, Druckvorschau-Dienste zur Verfügung zu stellen und dem Benutzer zusätzliche Informationen über die Operationen zur Verfügung zu stellen, die die Workflow-App für die Daten ausführen wird.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.

Im Rahmen dieses Ereignis-Handlers muss die Workflow-App ein Deferral-Objekt erhalten, wenn sie weiterhin mit dem Benutzer interagieren soll.As part of this event handler, the workflow app must acquire a deferral object if it will continue to interact with the user. Ohne eine Verzögerung betrachtet das Drucksystem den UI-Task als erledigt, wenn der XpsDataAvailable-Ereignis-Handler beendet wird oder eine asynchrone Methode aufgerufen wird.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. Wenn die App alle erforderlichen Informationen aus der Interaktion des Benutzers mit dem UI gesammelt hat, sollte sie die Verzögerung abschließen, damit das Drucksystem fortfahren kann.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();
}

Zusätzlich bietet die Instanz PrintWorkflowSubmittedOperation, die durch die Ereignisargumente bereitgestellt wird, die Option, den Druckauftrag abzubrechen oder anzuzeigen, dass der Auftrag erfolgreich ist, aber kein Ausgabedruckauftrag erforderlich ist.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. Dazu wird die Complete-Methode mit dem Wert PrintWorkflowSubmittedStatus aufgerufen.This is done by calling the Complete method with a PrintWorkflowSubmittedStatus value.

Hinweis

Wenn die Workflow-App den Druckauftrag abbricht, empfiehlt es sich dringend, eine Popup-Benachrichtigung zu senden, aus der hervorgeht, warum der Druckauftrag abgebrochen wurde.If the workflow app cancels the print job, it is highly recommended that it provide a toast notification indicating why the job was cancelled.

Abschließende Hintergrundarbeiten am Druckinhalt durchführenDo final background work on the print content

Nachdem das UI die Verzögerung des Ereignisses PrintTaskXpsDataAvailable abgeschlossen hat (oder wenn der Schritt des UIs umgangen wurde), löst das Drucksystem das Ereignis Submitted für die Hintergrundaufgabe aus.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. Im Handler für dieses Ereignis kann die Workflow-App auf alle Daten zugreifen, die das Ereignis XpsDataAvailable zur Verfügung stellt.In the handler for this event, the workflow app can get access to all of the same data provided by the XpsDataAvailable event. Im Gegensatz zu den vorherigen Ereignissen bietet Submitted jedoch auch Schreibzugriff auf den Inhalt des endgültigen Druckauftrags über eine PrintWorkflowTarget-Instanz.However, unlike any of the previous events, Submitted also provides write access to the final print job content through a PrintWorkflowTarget instance.

Das Objekt, mit dem die Daten für den endgültigen Druck gespoolt werden, hängt davon ab, ob auf die Quelldaten als Raw-Bity-Strom oder als XPS-Objektmodell zugegriffen wird.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. Wenn die Workflow-App über einen Byte-Stream auf die Quelldaten zugreift, wird ein Ausgabe-Byte-Stream bereitgestellt, in den die endgültigen Auftragsdaten geschrieben werden.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. Wenn die Workflow-App über das Objektmodell auf die Quelldaten zugreift, wird ein Document-Writer bereitgestellt, um Objekte in den Ausgabeauftrag zu schreiben.When the workflow app accesses the source data through the object model, a document writer is provided to write objects to the output job. In jedem Fall sollte die Workflow-App alle Quelldaten lesen, die erforderlichen Daten modifizieren und die geänderten Daten in das Ausgabeziel schreiben.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.

Wenn die Hintergrundaufgabe das Schreiben der Daten beendet hat, sollte sie Complete für das entsprechende PrintWorkflowSubmittedOperation-Objekt aufrufen.When the background task finishes writing the data, it should call Complete on the corresponding PrintWorkflowSubmittedOperation object. Sobald die Workflow-App diesen Schritt abgeschlossen hat und der Eventhandler Submitted beendet wurde, wird die Workflow-Sitzung geschlossen und der Benutzer kann den Status des endgültigen Druckauftrags über die Standard-Druckdialoge überwachen.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.

Letzte SchritteFinal steps

Druck-Workflow-App beim Drucker registrierenRegister the print workflow app to the printer

Ihre Workflow-App ist mit einem Drucker verbunden, der die gleiche Art der Übermittlung von Metadaten wie bei WSDAs verwendet.Your workflow app is associated with a printer using the same type of metadata file submission as for WSDAs. Tatsächlich kann eine einzelne UWP-Anwendung sowohl als Workflow-App als auch als WSDA fungieren, die Druckaufgabeeinstellungen ermöglicht.In fact, a single UWP application can act as both a workflow app and a WSDA that provides print task settings functionality. Führen Sie die entsprechenden WSDA-Schritte zum Anlegen der Metadaten-Zuordnung aus.Follow the corresponding WSDA steps for creating the metadata association.

Der Unterschied besteht darin, dass WSDAs zwar automatisch für den Benutzer aktiviert werden (die App wird immer gestartet, wenn der Benutzer über das zugehörige Gerät druckt), Workflow-Apps jedoch nicht.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. Sie haben eine eigene Richtlinie, die festgelegt werden muss.They have a separate policy that must be set.

Festlegen der Richtlinien für die Workflow-AppSet the workflow app's policy

Die Workflow-App-Richtlinie wird durch Powershell-Befehle auf dem Gerät festgelegt, das die Workflow-App ausführen soll.The workflow app policy is set by Powershell commands on the device that is to run the workflow app. Die Befehle Set-Printer, Add-Printer (bestehender Port) und Add-Printer (neuer WSD-Port) werden modifiziert, um das Festen von Workflow-Richtlinien zu ermöglichen.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: Workflow-apps werden nicht aktiviert werden.Disabled: Workflow apps will not be activated.
  • Uninitialized: Workflowanwendungen werden aktiviert, wenn der Workflow DCA im System installiert ist.Uninitialized: Workflow apps will be activated if the Workflow DCA is installed in the system. Wenn die App nicht installiert ist, wird trotzdem gedruckt.If the app is not installed, printing will still proceed.
  • Enabled: Workflow-Vertrag wird aktiviert werden, wenn der Workflow DCA im System installiert ist.Enabled: Workflow contract will be activated if the Workflow DCA is installed in the system. Wenn die App nicht installiert ist, schlägt das Drucken fehl.If the app is not installed, printing will fail.

Mit dem folgenden Befehl wird die Workflow-App auf dem angegebenen Drucker als erforderlich festgelegt.The following command makes the workflow app required on the specified printer.

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

Ein lokaler Benutzer kann diese Richtlinie auf einem lokalen Drucker ausführen, oder der Druckeradministrator kann diese Richtlinie auf dem Druckerserver ausführen.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. Die Richtlinie wird dann mit allen Client-Verbindungen synchronisiert.The policy will then be synchronized to all client connections. Der Druckeradministrator kann diese Richtlinie immer dann verwenden, wenn ein neuer Drucker hinzugefügt wird.The printer admin can use this policy whenever a new printer is added.

Siehe auchSee also

Workflow-app-BeispielWorkflow app sample

Windows.Graphics.Printing.Workflow-namespaceWindows.Graphics.Printing.Workflow namespace