Comment : étendre le schéma d'impression et créer des classes de système d'impression

Article
08/22/2008

Mise à jour : novembre 2007

Lorsque votre application doit traiter avec des périphériques d'impression spécialisée dont les fonctionnalités ne sont pas reflétées par le PrintSystemObject existant, et les classes PrintQueue, PrintCapabilities et PrintTicket, vous pouvez dériver de nouvelles classes par héritage, créer des versions étendues des classes PrintCapabilities et PrintTicket, et également étendre le Print Schema. Cet article présente les principales parties d'un tel projet ; mais il décrit une des façons d'étendre les classes managées appropriées.

Nous vous recommandons de lire cet article en association avec la documentation du Print Schema. Cet article présume que vous disposez au moins de principes de base sur le schéma et les documents PrintTicket et PrintCapabilities.

Cet article contient les sections suivantes.

Dériver une nouvelle classe par héritage
Déterminer si les fonctionnalités du périphérique sont déjà définies dans le schéma d'impression
Créer des types pour représenter les fonctionnalités du périphérique
Étendre les classes PrintCapabilities et PrintTicket
- Étendre la classe PrintTicket
- Étendre la classe PrintCapabilities
Lire et écrire des flux XML PrintCapabilities et PrintTicket
Surcharger et étendre les propriétés et méthodes
Étendre les fonctionnalités de schéma
Étendre l'espace de noms System.Printing.IndexedProperties

Exemple

L'exemple de projet présenté dans cet article ne fournit pas tous les détails nécessaires à la compilation et à l'exécution d'une application. Il est destiné à vous donner une idée des principales étapes nécessaires pour étendre les fonctionnalités des espaces de noms System.Printing et System.Printing.IndexedProperties à des périphériques d'impression disposant de fonctionnalités qui ne sont pas explicitement prises en charge dans ces espaces de noms. Les exemples de code sont fournis uniquement lorsque des détails concrets sont nécessaires.

En outre, les exemples de code ne contiennent pas nécessairement des méthodes de programmation appropriées ni du code sécurisé. Tout ce qui ne concerne pas directement le sujet de l'article est omis.

Pour finir, cet article s'adresse en priorité aux développeurs d'applications plutôt qu'aux développeurs de pilotes de périphériques. C'est pourquoi, l'accent est mis sur l'écriture d'objets PrintTicket, plutôt que sur celle d'objets PrintCapabilities.

Dériver une nouvelle classe par héritage

Commencez par dériver une classe pour représenter votre périphérique de la classe PrintQueue. Dans l'exemple de code ci-dessous, une classe BrailleEmbosser est dérivée. Le Braille est un langage lisible par les utilisateurs malvoyants ou non-voyants car ses symboles sont composés de points en relief sur le papier afin de pouvoir être lus avec les doigts. Une imprimante Braille est tout simplement une imprimante qui imprime le Braille. Certains pilotes d'imprimantes Braille permettent de traduire le Braille standard en Braille Grade 3, parfois appelé Braille 3, qui est une version compacte du Braille utilisant de nombreuses contractions et abréviations. Cet exemple fournit une propriété pour représenter cette fonctionnalité.

Souvent vous devrez aussi surcharger certaines méthodes et propriétés héritées. Pour plus d'informations, consultez Surcharger et étendre les propriétés et méthodes.

class BrailleEmbosser : PrintQueue
{
   public BrailleEmbosser(PrintServer ps, String s, PrintSystemDesiredAccess access) : base(ps, s, access)
   {
      // Optionally, include here code to set non-inherited fields.
   }

   // other constructor declarations omitted

   private Boolean isBraille3Enabled;

   public Boolean IsBraile3Enabled
   {
      get { return isBraille3Enabled; }
      set { isBraille3Enabled = value; }
   }

   // remainder of class definition omitted
}

Déterminer si les fonctionnalités du périphérique sont déjà définies dans le schéma d'impression

Les classes PrintTicket et PrintCapabilities possèdent des propriétés représentant la plupart des fonctionnalités d'impression communes ; toutefois, d'autres fonctionnalités définies dans la spécification Print Schema Public Keywords ne sont pas explicitement reflétées dans ces classes. Pour obtenir la liste des fonctionnalités communes, consultez uniquement les propriétés de la classe PrintCapabilities. Lisez la spécification pour déterminer si les fonctionnalités spécifiques au périphérique y sont définies. Pour toute fonctionnalité qui est incluse dans la spécification, l'utilisation du modèle de spécification présente un avantage : une terminologie et un modèle communs permettent d'utiliser les documents XML PrintTicket créés pour un périphérique avec un autre périphérique. (Le second périphérique peut provenir d'un autre fabricant et peut avoir été conçu après la date de création d'origine du document PrintTicket.) Les tickets d'impression peuvent être incorporés dans les documents, afin que les intentions d'impression et de mise en forme de l'auteur puissent être exécutées lorsque le document est distribué à des utilisateurs disposant d'imprimantes différentes.

Dans le reste de cet article, les fonctionnalités explicitement prises en charge par les classes PrintTicket et PrintCapabilities seront appelées « fonctionnalités communes ». Les fonctionnalités définies dans la spécification Print Schema Public Keywords qui ne sont pas explicitement prises en charge par ces deux classes, seront appelées « fonctionnalités définies ». Les fonctionnalités qui ne sont pas définies dans la spécification Mots clés publics seront appelées « nouvelles fonctionnalités ».

Il est également possible que votre périphérique possède une fonctionnalité qui correspond presque exactement à une fonctionnalité définie, mais dotée d'une ou plusieurs options supplémentaires qui ne sont pas reconnues dans la spécification Print Schema Public Keywords. Le Print Schema peut être étendu pour gérer ces fonctionnalités d'une façon qui permet de tirer parti de la définition existante autant que possible. Pour plus d'informations sur l'utilisation d'une de ces fonctionnalités, consultez Étendre les fonctionnalités de schéma ci-dessous.

Créer des types pour représenter les fonctionnalités du périphérique

Les propriétés du PrintTicket et du PrintCapabilities qui correspondent aux fonctionnalités d'impression possèdent des types spéciaux, généralement des énumérations qui représentent une fonctionnalité et ses valeurs possibles. Par exemple, l'énumération Collation est le type de la propriété PrintTicket.Collation. Il s'agit aussi du type des membres de la collection qui est le type de la propriété PrintCapabilities.CollationCapability.

Créez des classes pour les fonctionnalités définies et les nouvelles fonctionnalités de votre périphérique en utilisant les classes existantes comme modèles. Dans l'exemple de code ci-dessous, une énumération BrailleGrade3 est déclarée. Elle est construite sur le modèle de l'énumération Collation car la traduction en Grade 3 est analogue à l'assemblage : les imprimantes doivent au moins prendre en charge un type de sortie (assemblée ou non assemblée) car ils sont mutuellement exhaustifs. Certaines imprimantes prennent en charge les deux types. (Les imprimantes qui prennent uniquement en charge les sorties assemblées sont rares, mais vous devez tenir compte de cette éventualité.) Il peut aussi exister des imprimantes qui prennent en charge la sortie Braille non traduite uniquement, la sortie traduite uniquement (peu probable), ou les deux. L'énumération BrailleGrade3 comprend une valeur Inconnue pour la même raison que Collation : pour gérer les situations dans lesquelles une application de génération de documents PrintTicket a affecté une valeur non reconnue dans la spécification Print Schema Public Keywords à une fonctionnalité d'assemblage. Si votre application crée un objet PrintTicket en utilisant un tel document, alors la propriété PrintTicket.Collation a la valeur Inconnue. La valeur Inconnue n'est jamais utilisée par des objets PrintCapabilities.

public enum BrailleGrade3 { Translated, Untranslated, Unknown }

Les énumérations ne constituent pas toujours la meilleure façon de représenter une fonctionnalité. Parfois, une classe d'un type référence est plus appropriée. Cela s'avère particulièrement vrai lorsque la fonctionnalité possède une structure imbriquée de parties subordonnées qui ont leur propre valeur. Par exemple, la classe PageMediaSize a les propriétés Height et Width. PageMediaSize est le type de la propriété PrintTicket.PageMediaSize. Il s'agit aussi du type des membres de la collection qui est le type de la propriété PrintCapabilities.PageMediaSizeCapability.

Étendre les classes PrintCapabilities et PrintTicket

Bien que les classes PrintTicket et PrintCapabilities ne puissent pas être héritées, vous pouvez étendre le Print Schema pour reconnaître les fonctionnalités définies et les nouvelles fonctionnalités.

Étendre la classe PrintTicket

Pour utiliser la classe PrintTicket avec le système étendu de fonctionnalités, vous devez procéder comme suit. Pour plus d'informations, reportez-vous au passage correspondant ci-dessous.

Procédure globale pour étendre la classe PrintTicket

Si le périphérique possède de nouvelles fonctionnalités, créez une classe pour encapsuler les nouvelles fonctionnalités. Pour plus d'informations, consultez Créer une classe NewFeaturesPrintTicket.
Si le périphérique possède des fonctionnalités définies, créez une classe pour encapsuler les fonctionnalités définies. Pour plus d'informations, consultez Créer une classe DefinedFeaturesPrintTicket.
Créez une classe pour représenter un ticket d'impression complet. Dans votre application, cette classe jouera le rôle qu'aurait la classe PrintTicket si le périphérique n'avait pas de fonctionnalités définies ou de nouvelles fonctionnalités. Pour plus d'informations, consultez Créer une classe WholePrintTicket.

Procédure permettant de créer une classe NewFeaturesPrintTicket

Si le périphérique possède de nouvelles fonctionnalités, déclarez une classe pour encapsuler ces fonctionnalités. Appelez-la NewFeaturesPrintTicket.
Affectez des propriétés à votre nouvelle classe pour représenter les nouvelles fonctionnalités du périphérique. Généralement, chaque propriété sera d'un type que vous créez, habituellement une énumération. Consultez Créer des types pour représenter les fonctionnalités du périphérique ci-avant.
Affectez une propriété supplémentaire à la nouvelle classe, appelons-la PrivateNamespace, qui contiendra une référence à l'espace de noms XML privé qui définit les nouvelles fonctionnalités du périphérique. Vous aurez besoin de cette chaîne lors de l'écriture des balises XML dans les documents PrintCapabilities et PrintTicket. Consultez Lire et écrire des flux XML PrintCapabilities et PrintTicket ci-après.
Affectez deux constructeurs à la classe. Ces constructeurs doivent être modelés sur les deux constructeurs du PrintTicket. Un n'utilise pas de paramètres et l'autre utilise un objet Stream avec contenu XML. Le flux XML sera un document PrintTicket qui définit les nouvelles fonctionnalités plutôt que les fonctionnalités communes. (Consultez Print Schema-Related Technologies et PrintTicket Schema and Document Construction.) Le constructeur avec le paramètre doit lever des exceptions sur le modèle du constructeur à un paramètre de la classe PrintTicket.
Créez une méthode GetXmlStream et une méthode SaveTo pour la classe. Utilisez le mot clé d'accès "internal" pour les deux méthodes. Elles sont destinées à faire correspondre les fonctionnalités des méthodes PrintTicket de ces noms, si ce n'est qu'elles traiteront les documents PrintTicket qui définissent les nouvelles fonctionnalités plutôt que les fonctionnalités communes. Ces méthodes doivent s'assurer que les flux qu'elles génèrent ont une déclaration d'espace de noms supplémentaire (la valeur de la propriété PrivateNamespace) dans l'élément d'ouverture <PrintTicket … >. Consultez Lire et écrire des flux XML PrintCapabilities et PrintTicket ci-après.

Procédure permettant de créer une classe DefinedFeaturesPrintTicket

Si le périphérique possède des fonctionnalités définies, déclarez une classe pour encapsuler ces fonctionnalités. Appelez-la DefinedFeaturesPrintTicket. Elle doit être construite de la même façon que la classe NewFeaturesPrintTicket ci-dessus, avec les exceptions suivantes.
- Les propriétés de la classe doivent avoir des noms qui correspondent exactement au nom de la fonctionnalité appropriée dans la spécification Print Schema Public Keywords.
- Ne créez pas une propriété PrivateNamespace. L'espace de noms pour les fonctionnalités définies est identique pour les fonctionnalités communes. Consultez Lire et écrire des flux XML PrintCapabilities et PrintTicket ci-après.
- Les méthodes GetXmlStream et SaveTo ne génèrent pas de flux avec une déclaration d'espace de noms supplémentaire.

Procédure permettant de créer une classe WholePrintTicket

Déclarez une classe qui représentera un ticket d'impression complet et, qui jouera le rôle dans votre application qu'aurait joué la classe PrintTicket si le périphérique n'avait pas de fonctionnalités définies ou de nouvelles fonctionnalités. Appelez-la WholePrintTicket.
Affectez une propriété à WholePrintTicket, appelez-la CommonFeatures, de type PrintTicket.
Affectez à WholePrintTicket une seule des deux propriétés supplémentaires suivantes ou les deux, selon que le périphérique possède de nouvelles fonctionnalités, des fonctionnalités définies ou les deux.
- NewFeatures de type NewFeaturesPrintTicket.
- DefinedFeatures de type DefinedFeaturesPrintTicket.
Affectez deux constructeurs à WholePrintTicket. Un qui n'utilise pas de paramètres et l'autre qui utilise un objet Stream avec contenu XML. Le constructeur avec paramètre effectue les opérations suivantes.
1. Transmettre le Stream au constructeur pour l'objet PrintTicket référencé par la propriété CommonFeatures. Ce constructeur ignore simplement les balises du Stream qui ne concernent pas les fonctionnalités communes.
2. Transmettre le Stream au constructeur de l'objet NewFeaturesPrintTicket référencé par la propriété NewFeatures. Ce constructeur ignore simplement les balises du Stream qui ne concernent pas les nouvelles fonctionnalités. S'il existe des balises de nouvelles fonctionnalités, le Stream commence par <psf:PrintTicket xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1" xmlns:espace de noms abrégé=nom complet de l'espace de noms>, où nom complet de l'espace de noms correspond à l'URL utilisée pour identifier le schéma qui définit les nouvelles fonctionnalités et espace de noms abrégé correspond à son abréviation. Pour plus d'informations, consultez Lire et écrire des flux XML PrintCapabilities et PrintTicket ci-après.
3. Transmettre le Stream au constructeur de l'objet DefinedFeaturesPrintTicket référencé par la propriété DefinedFeatures. Ce constructeur ignore simplement les balises du Stream qui ne concernent pas les fonctionnalités définies.
Créez une méthode GetXmlStream et une méthode SaveTo pour la classe. Elles sont destinées à faire correspondre les fonctionnalités des méthodes PrintTicket portant ces noms. Elles doivent avoir les caractéristiques suivantes.
- Chaque méthode doit appeler la méthode correspondante du même nom dans les objets référencés par la propriété CommonFeatures, la propriété DefinedFeatures (si elle existe) et la propriété NewFeatures (si elle existe).
- Chaque méthode doit concaténer les flux générés par les appels décrits précédemment. Bien sûr, vous devez supprimer toutes les balises à l'exception de la balise de fin </PrintTicket>, et toutes les balises à l'exception de la balise de début <PrintTicket … >. Hormis s'il n'y a pas de nouvelles fonctionnalités, la balise de début doit avoir une déclaration d'espace de noms supplémentaire. (Voir étape 4b.) C'est pourquoi, vous devez toujours envisager que le flux de nouvelles fonctionnalités (s'il existe) soit le premier dans le flux concaténé car il possède déjà cette déclaration dans sa balise de début <PrintTicket … >.
- Pour effectuer la concaténation, les méthodes GetXmlStream et SaveTo de la classe WholePrintTicket doivent fonctionner sur un flux temporaire interne dans un premier temps. Plus précisément, les trois classes sérialiseront leur contenu dans le flux temporaire, effectueront la concaténation (et le nettoyage – voir ci-dessous), et généreront le résultat de la concaténation dans le flux de sortie final.
- Après la concaténation, les méthodes GetXmlStream et SaveTo de la classe WholePrintTicket supprimeront les exemplaires d'éléments en double et en triple dans le flux avant de retourner le flux final. Ces entrées en double et en triple sont dans le flux car chacun des trois objets, PrintTicket, NewFeaturesPrintTicket et DefinedFeaturesPrintTicket, conservent l'intégralité du document PrintTicket d'origine qui a été utilisé pour le construire, même si chacun d'eux expose uniquement un sous-ensemble du document dans ses propriétés.
- Vous pouvez éviter l'étape de nettoyage décrite précédemment si votre constructeur WholePrintTicket(Stream) (voir ci-avant) divise le flux entrant en trois parties en séparant les flux d'éléments de balise définis, nouveaux et communs. Chacun de ces plus petits flux est ensuite passé au constructeur approprié des trois propriétés de WholePrintTicket. Cette technique nécessite l'ajout d'une balise de fermeture </PrintTicket> à chacun des trois flux. Au flux des propriétés CommonFeatures et DefinedFeatures, ajoutez une balise de début telle que celle qui suit : <psf:PrintTicket xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1">. La balise de début du constructeur de la propriété NewFeatures ajoute un espace de noms privé comme suit : <psf:PrintTicket xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1" xmlns:espace de noms abrégé=nom complet de l'espace de nom>, où nom complet de l'espace de noms correspond à l'URL utilisée pour identifier le schéma qui définit les nouvelles fonctionnalités et espace de noms abrégé correspond à son abréviation.

L'exemple de code suivant montre une partie du résultat de cette procédure lorsqu'elle est appliquée à l'exemple d'imprimante Braille. (Pour des considérations liées à l'espace et pour simplifier, une grande partie a été omise.) Notez que la propriété BrailleGrade3 est un type Nullable<T>. Cela suit le modèle des propriétés du PrintTicket telles que Collation. L'exemple suppose qu'il y a à la fois des nouvelles fonctionnalités et des fonctionnalités définies, même s'il ne spécifie aucune fonctionnalités définies spécifiques.

class NewFeaturesPrintTicket
{
    public NewFeaturesPrintTicket()
    {
        // Optionally, initialize fields. For example:
        privateNamespace = "http://www.AjaxEmbossers.com/schemas/deluxemodels/v.1.0";
    }

    public NewFeaturesPrintTicket(Stream printTicketDocument)
    {
    // Parse the stream and initialize fields representing features here.
    // Optionally, initialize other fields. For example:
    privateNamespace = "http://www.AjaxEmbossers.com/schemas/deluxemodels/v.1.0";
    }

    private Nullable<BrailleGrade3> brailleGrade3;
    public Nullable<BrailleGrade3> BrailleGrade3
    {
        get { return brailleGrade3; }
        set { brailleGrade3 = value;}
    }

    private String privateNamespace;
    public String PrivateNamespace
    {
        get { return privateNamespace; }
        set { privateNamespace = value; }
    }
}

class DefinedFeaturesPrintTicket
{
  // Details omitted. Use the NewFeaturesPrintTicket
  // as a model, but leave out the privateNamespace field
  // and property.
}

class WholePrintTicket
{
    public WholePrintTicket()
    {
        commonFeatures = new PrintTicket();
        newFeatures = new NewFeaturesPrintTicket();
        definedFeatures = new DefinedFeaturesPrintTicket();
    }

    public WholePrintTicket(Stream wholePrintTicket)
    {
         // Method 1: Pass the stream to the three constructors.
         // Be sure to reset the read-write position of the stream
         // to the beginning of the stream after each call to a 
         // constructor. 
         // commonFeatures = new PrintTicket(wholePrintTicket);
              // reset read-write head here
        // newFeatures = new NewFeaturesPrintTicket(wholePrintTicket);
              // reset read-write head here
        // definedFeatures = new DefinedFeaturesPrintTicket(wholePrintTicket);
              // reset read-write head here

        // Method 2: Parse the stream and split it into three streams. 
        // Then pass them to the constructors of the three properties. 
        // commonFeatures = new PrintTicket(commonFeaturesPrintTicketDocument);
        // newFeatures = new NewFeaturesPrintTicket(newFeaturesPrintTicketDocument);
        // definedFeatures = new DefinedFeaturesPrintTicket(definedFeaturesPrintTicketDocument);
    }

    private PrintTicket commonFeatures;
    public PrintTicket CommonFeatures
    {
        get { return commonFeatures; }
        set { commonFeatures = value;}
    }

    private PrintTicket newFeatures;
    public PrintTicket NewFeatures
    {   // Details omitted. See CommonFeatures above.}

    private PrintTicket definedFeatures;
    public PrintTicket DefinedFeatures
    {   // Details omitted. See CommonFeatures above.}
}

Étendre la classe PrintCapabilities

Pour utiliser la classe PrintCapabilities avec votre périphérique, vous devez l'étendre d'une façon semblable à celle utilisée pour étendre la classe PrintTicket. Étant donné que vous pouvez utiliser votre extension du PrintTicket comme modèle, seule une vue d'ensemble est présentée ici.

Créez trois classes, une pour encapsuler les nouvelles fonctionnalités (NewFeaturesPrintCapabilities), une pour encapsuler les fonctionnalités définies (DefinedFeaturesPrintCapabilities), et une pour représenter un document PrintCapabilities entier (WholePrintCapabilities).
Les types de propriétés des deux premières classes sont généralement ReadOnlyCollection<T>. Utilisez les propriétés existantes du PrintCapabilities, telles que CollationCapability, comme modèles.
Selon le modèle de la classe PrintCapabilities existante, les noms de propriétés doivent se terminer par "Capability" ; par exemple, BrailleGrade3Capability.
La propriété PrivateNamespace de la classe NewFeaturesPrintCapabilities sera identique à celle créée pour NewFeaturesPrintTicket.
Aucune des classes n'aura des méthodes autres que celles héritées de la classe Object.
Chacune des classes possèdera un seul constructeur utilisant Stream comme paramètre. Stream sera un document PrintCapabilities.
Le constructeur DefinedFeaturesPrintCapabilities doit vérifier que le Stream qui lui a été passé est conforme à la Print Schema Framework avant d'utiliser Stream pour initialiser les propriétés. (Pour ce faire, une méthode simple consiste à passer d'abord le Stream au constructeur PrintCapabilities. Si aucune exception n'est levée, le flux est valide.)
Le constructeur NewFeaturesPrintCapabilities doit vérifier que le Stream qui lui a été passé est conforme à l'espace de noms privé avant d'utiliser Stream pour initialiser les propriétés.
Les constructeurs DefinedFeaturesPrintCapabilities et NewFeaturesPrintCapabilities lèvent des exceptions sur le modèle du constructeur PrintCapabilities existant.
La classe WholePrintCapabilities aura les propriétés CommonFeatures, DefinedFeatures et NewFeatures. Ces propriétés seront de type PrintCapabilities, DefinedFeaturesPrintCapabilities et NewFeaturesPrintCapabilties, respectivement. Chacune sera construite sur le modèle des propriétés de WholePrintTicket.
Le constructeur de la classe WholePrintCapabilities utilisera un seul paramètre Stream représentant un document PrintCapabilities complet. Le constructeur doit passer le Stream d'entrée complet aux trois constructeurs pour les propriétés de ses membres. Étant donné que la classe WholePrintCapabilities ne possède aucune méthode d'exportation de ses paramètres au format XML (comme les méthodes GetXmlStream et SaveTo de la classe WholePrintCapabilities), la présence de balises en double ou en triple dans ces trois propriétés est sans conséquence.

Pour plus d'informations, consultez PrintCapabilities Schema and Document Construction.

Lire et écrire des flux XML PrintCapabilities et PrintTicket

Le travail principal des constructeurs et méthodes des classes PrintTicket et PrintCapabilities existantes et des nouvelles classes créées précédemment dans Étendre les classes PrintCapabilities et PrintTicket consiste à lire, analyser, écrire et parfois valider des objets Stream dont le contenu est soit un document PrintTicket, soit un document PrintCapabilities. Vous devez être familiarisé avec E/S de fichier de base et les méthodes de ces classes. Étant donné le contenu de ces flux XML, vous devez aussi vous familiariser avec la prise en charge de la lecture et de l'écriture XML décrite dans Options de traitement XML dans le .NET Framework. Si votre application fonctionne avec des documents XML Paper Specification (XPS), il y a des API dans les espaces de noms System.Windows.Xps, System.Windows.Xps.Packaging et System.Windows.Xps.Serialization destinés à la lecture et à l'écriture dans des documents XPS, notamment à la lecture et à l'écriture de PrintTicket. Pour plus d'informations sur l'ajout d'une relation à un PrintTicket dans un package, consultez aussi PackageRelationship.

Des exemples complets de documents PrintTicket et PrintCapabilities sont disponibles dans PrintTicket Example et PrintCapabilities Document Example.

L'élément suivant est un exemple simple d'un document PrintCapabilities dans lequel une seule fonctionnalité du périphérique a été omise. La fonctionnalité illustrée, DocumentCollate, est représentée par les propriétés PrintCapabilities.CollationCapability et PrintTicket.Collation.

<psf:PrintCapabilities xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1">

   <!-- other features omitted --> 
   
   <psf:Feature name="psk:DocumentCollate">
        <psf:Property name="psf:SelectionType">
            <psf:Value xsi:type="xsd:QName">psk:PickOne</psf:Value>
        </psf:Property>
        <psf:Property name="psk:DisplayName">
            <psf:Value xsi:type="xsd:string">Collate Copies</psf:Value>
        </psf:Property>
        <psf:Option name="psk:Collated" constrained="psk:None">
            <psf:Property name="psk:DisplayName">
                <psf:Value xsi:type="xsd:string">Yes</psf:Value>
            </psf:Property>
        </psf:Option>
        <psf:Option name="psk:Uncollated" constrained="psk:None">
            <psf:Property name="psk:DisplayName">
                <psf:Value xsi:type="xsd:string">No</psf:Value>
            </psf:Property>
        </psf:Option>
    </psf:Feature>
                   
   <!-- other features omitted --> 
   
</PrintCapabilities>

Notez que chaque option possible pour la fonctionnalité est répertoriée (assemblée et non assemblée) et leur état (avec contrainte ou non) est identifié. Dans un document PrintCapabilities complet, l'état de toutes les options de chaque fonctionnalité est identifié ; par conséquent, le document est un type de capture instantanée de la configuration du périphérique.

L'élément suivant est un exemple simple d'un document PrintTicket qui possède une seule fonctionnalité.

<psf:PrintTicket xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1">
  
  <!-- other features omitted -->
  
  <psf:Feature name="psk:DocumentCollate">
    <psf:Option name="psk:Collated" />
  </psf:Feature>  
    
  <!-- other features omitted -->
  
</PrintTicket>

Notez que la structure peut être plus simple car il n'est pas nécessaire qu'un document PrintTicket spécifie explicitement l'état de toutes les options. Il doit uniquement identifier l'option demandée.

La syntaxe et la structure de la fonctionnalité est définie dans DocumentCollate par la Print Schema Framework et les Print Schema Public Keywords. Lorsque vous utilisez de nouvelles fonctionnalités, vous utilisez celles définies dans un espace de noms XML privé défini dans un schéma supplémentaire. Généralement, ce dernier est fourni par le fabricant du périphérique, une association ou une organisation à but non lucratif ; toutefois, vous pouvez aussi le créer vous-même. Utilisez la Print Schema Framework existante et les Print Schema Public Keywords pour découvrir la syntaxe nécessaire et rechercher des modèles sur lesquels vous pouvez baser vos définitions. Microsoft a créé un espace de noms afin d'étendre le système PrintCapabilities et PrintTicket à son nouveau pilote Microsoft XPS Document Writer (MXDW). Pour plus d'informations, consultez Paramètres de configuration MXDW.

Si nous supposons qu'une société d'imprimante Ajax fictive a défini la fonctionnalité de traduction BrailleGrade3 de façon semblable à la façon dont Microsoft a défini la fonctionnalité d'assemblage de document, nous pouvons voir à quoi ressemble les entrées des documents PrintCapabilities et PrintTicket pour la fonctionnalité. Notez que l'espace de noms lorsque la fonctionnalité est définie doit être déclaré dans les balises de début <PrintCapabilities … > et <PrintTicket … >.

Balises du document PrintCapabilities

<psf:PrintCapabilities xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
           xmlns:ajax="http://www.AjaxEmbossers.com/schemas/deluxemodels" version="1">

   <!-- other features omitted --> 
   
   <psf:Feature name="ajax:BrailleGrade3Translation">
        <psf:Property name="psf:SelectionType">
            <psf:Value xsi:type="xsd:QName">psk:PickOne</psf:Value>
        </psf:Property>
        <psf:Property name="psk:DisplayName">
            <psf:Value xsi:type="xsd:string">Braille3 translation</psf:Value>
        </psf:Property>
        <psf:Option name="ajax:Translated" constrained="psk:None">
            <psf:Property name="psk:DisplayName">
                <psf:Value xsi:type="xsd:string">Yes</psf:Value>
            </psf:Property>
        </psf:Option>
        <psf:Option name="ajax:Untranslated" constrained="psk:None">
            <psf:Property name="psk:DisplayName">
                <psf:Value xsi:type="xsd:string">No</psf:Value>
            </psf:Property>
        </psf:Option>
    </psf:Feature>
                   
   <!-- other features omitted --> 
   
</PrintCapabilities>

Balises du document PrintTicket

<psf:PrintTicket xmlns:psf="https://schemas.microsoft.com/windows/2003/08/printing/printschemaframework" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
           xmlns:ajax="http://www.AjaxEmbossers.com/schemas/deluxemodels" version="1">
  
  <!-- other features omitted -->
  
  <psf:Feature name="ajax:BrailleGrade3Translation">
    <psf:Option name="ajax:Translated" />
  </psf:Feature>  
    
  <!-- other features omitted -->
  
</PrintTicket>

Pour plus d'informations sur l'écriture de documents PrintTicket qui gèrent de nouvelles fonctionnalités, consultez Creating a Device-Specific PrintTicket. Pour obtenir de la documentation sur la création de documents PrintTicket et PrintCapabilities, consultez les sections PrintCapabilities Schema and Document Construction et PrintTicket Schema and Document Construction dans la documentation du schéma d'impression.

Surcharger et étendre les propriétés et méthodes

Les méthodes de classes qui utilisent un paramètre PrintTicket ou retourne un PrintTicket, que vous souhaitez utiliser avec votre système de fonctionnalités étendues, doivent être remplacées par une méthode qui utilise WholePrintTicket à la place de PrintTicket. De la même façon, les propriétés de type PrintTicket que vous souhaitez utiliser doivent être remplacées par des propriétés de type WholePrintTicket. Ces considérations s'appliquent, une fois que ce qui devait l'être a été changé, à PrintCapabilities et WholePrintCapabilities.

Lorsque la classe qui héberge la méthode ou la propriété peut être héritée, vous pouvez dériver une classe et surcharger la méthode ou la propriété pour utiliser WholePrintTicket à la place de PrintTicket.

Si la classe d'hébergement ne peut pas être héritée, vous devez l'étendre de la façon dont PrintTicket et PrintCapabilities ont été étendus précédemment : créez une classe qui possède la classe d'hébergement comme membre. Ensuite, affectez aux méthodes de classe externe et aux propriétés les mêmes noms que ceux des méthodes qui utilisent (ou retournent) le paramètre PrintTicket ou PrintCapabilities. Généralement, la classe externe doit correspondre aux fonctionnalités de la classe interne, mais utilise le paramètre WholePrintTicket ou WholePrintCapabilities à la place du paramètre PrintTicket ou PrintCapabilities. Pour les propriétés de la classe interne qui sont de type PrintTicket ou PrintCapabilities, vous devez aussi créer une propriété du même nom dans la classe externe qui utilise WholePrintTicket or WholePrintCapabilities.

Les méthodes les plus importantes dont vous aurez probablement besoin pour surcharger sont les deux versions du MergeAndValidatePrintTicket La classe BrailleEmbosser (consultez Dériver une nouvelle classe par héritage ci-avant) aura besoin de remplacements qui utilisent des paramètres WholePrintTicket et ajoutent une logique pour valider les tickets avec de nouvelles fonctionnalités par rapport au schéma de l'espace de noms privé. Vous pouvez soit surcharger les méthodes existantes, soit en créer de nouvelles nommées MergeAndValidateWholePrintTicket.

Les deux méthodes qui retournent un PrintTicket sont ConvertDevModeToPrintTicket et Clone. Dans .NET Framework, il existe 15 autres méthodes, sans compter les surcharges, qui utilisent un paramètre PrintTicket et 19 propriétés de type PrintTicket. Cependant, il est improbable qu'une application donnée en utilise un grand nombre ; par conséquent, votre charge de travail ne sera pas aussi élevée que ces nombres le suggèrent. Heureusement, la seule méthode qui retourne un objet PrintCapabilities est GetPrintCapabilities et il n'existe pas de propriétés avec le type PrintCapabilities.

Étendre les fonctionnalités de schéma

Le seul cas où l'extension du Print Schema s'avère nécessaire ne se résume pas aux fonctionnalités entièrement nouvelles. Il est aussi possible qu'un périphérique propose de nouvelles options non définies pour une fonctionnalité familière définie. Étant donné qu'un espace de noms privé doit être utilisé pour les nouvelles options non définies tout comme pour une fonctionnalité entièrement nouvelle, il est probablement plus simple de traiter ces fonctionnalités étendues comme vous le feriez pour de nouvelles fonctionnalités (mais utilisez les noms du schéma et ceux de ses options qui sont déjà définies) : hébergez-les dans NewFeaturesPrintTicket et NewFeaturesPrintCapabilities. La présentation des informations nécessaires pour implémenter ce type d'extension de schéma n'est pas couverte par cet article, mais notez que la concaténation qui doit être effectuée par les méthodes WholePrintTicket.GetXmlStream et WholePrintTicket.SaveAs deviendra plus complexe.

Étendre l'espace de noms System.Printing.IndexedProperties

Si vous souhaitez tirer parti des API dans l'espace de noms System.Printing.IndexedProperties, vous devez dériver une nouvelle classe de PrintProperty. Vous devez procéder ainsi si une propriété créée pour la classe dérivée de PrintQueue est d'un type qui n'est pas représenté par l'une des classes existantes dans System.Printing.IndexedProperties. Pour obtenir des exemples de ce qui peut être fait avec l'espace de noms System.Printing.IndexedProperties, consultez Comment : cloner une imprimante et Comment : obtenir les propriétés de l'objet de système d'impression sans réflexion.

Cela n'est pas nécessaire pour l'exemple précédent, étant donné que la seule propriété ajoutée à la classe BrailleEmbosser est IsBraile3Enabled, qui est Boolean. Il existe déjà une classe System.Printing.IndexedProperties.PrintBooleanProperty.

Voir aussi

Partager via