Comment afficher l’état de l’imprimante dans une application d’appareil UWP

Dans Windows 8.1, les utilisateurs peuvent vérifier l’état de leur imprimante à partir de l’interface utilisateur moderne d’une application d’appareil UWP. Cette rubrique utilise la version C# des paramètres d’impression et de l’exemple de notifications d’impression pour montrer comment interroger l’état de l’imprimante et l’afficher. Pour en savoir plus sur les applications d’appareil UWP en général, consultez Meet UWP device apps.

La version C# des paramètres d’impression et de l’exemple de notifications d’impression utilise la page InkLevel.xaml pour montrer comment obtenir l’état de l’imprimante (dans ce cas, le niveau d’encre) et l’afficher. Une classe d’assistance d’impression est utilisée pour créer un contexte d’appareil (IPrinterExtensionContext) et effectuer les requêtes d’appareil. The PrinterHelperClass.cs file is in the DeviceAppForPrintersLibrary project and uses APIs defined in the PrinterExtensionLibrary project. La bibliothèque d’extensions d’imprimante offre un moyen pratique d’accéder aux interfaces d’extension d’imprimante du pilote d’impression v4. Pour plus d’informations, consultez la vue d’ensemble de la bibliothèque d’extensions d’imprimante.

Prerequisites

Avant de commencer :

1. Vérifiez que votre imprimante est installée à l’aide d’un pilote d’impression v4. Pour plus d’informations, consultez Développement de pilotes d’impression v4.

2. Configurez votre PC de développement. See Getting started for info about downloading the tools and creating a developer account.

3. Associez votre application au Windows Store. Consultez l’étape 1 : Créer une application d’appareil UWP pour plus d’informations sur ce sujet.

4. Créez des métadonnées d’appareil pour votre imprimante qui l’associe à votre application. Consultez l’étape 2 : Créer des métadonnées d’appareil pour en savoir plus.

5. If you're writing your app with C# or JavaScript, add the PrinterExtensionLibrary and DeviceAppForPrintersLibrary projects to your UWP device app solution. Vous trouverez chacun de ces projets dans les paramètres d’impression et l’exemple de notifications d’impression .

   Note

   Étant donné que C++ peut accéder directement à COM, les applications C++ ne nécessitent pas de bibliothèque distincte pour fonctionner avec le contexte d’appareil d’imprimante COM.

Étape 1 : Rechercher l’imprimante

Avant de créer un contexte d’appareil, l’application doit déterminer l’ID de l’appareil de l’imprimante. Pour ce faire, l’exemple utilise la EnumerateAssociatedPrinters méthode pour rechercher toutes les imprimantes attachées au PC. Ensuite, il vérifie le conteneur pour chaque imprimante et recherche une association en comparant la propriété PackageFamilyName de chaque conteneur.

This example shows the EnumerateAssociatedPrinters method from the InkLevel.xaml.cs file:

async void EnumerateAssociatedPrinters(object sender, RoutedEventArgs e)
{
    // Reset output text and associated printer array.
    AssociatedPrinters.Items.Clear();
    BidiOutput.Text = "";

    // GUID string for printers.
    string printerInterfaceClass = "{0ecef634-6ef0-472a-8085-5ad023ecbccd}";
    string selector = "System.Devices.InterfaceClassGuid:=\"" + printerInterfaceClass + "\"";

    // By default, FindAllAsync does not return the containerId for the device it queries.
    // We have to add it as an additional property to retrieve. 
    string containerIdField = "System.Devices.ContainerId";
    string[] propertiesToRetrieve = new string[] { containerIdField };

    // Asynchronously find all printer devices.
    DeviceInformationCollection deviceInfoCollection = await DeviceInformation.FindAllAsync(selector, propertiesToRetrieve);

    // For each printer device returned, check if it is associated with the current app.
    for (int i = 0; i < deviceInfoCollection.Count; i++)
    {
        DeviceInformation deviceInfo = deviceInfoCollection[i];
        FindAssociation(deviceInfo, deviceInfo.Properties[containerIdField].ToString());
    }
}

La FindAssociation méthode, appelée par EnumerateAssociatedPrinters, vérifie si une imprimante est associée à l’application actuelle. En d’autres termes, cette méthode vérifie si l’application est une application d’appareil UWP. Cette association existe lorsque l’application et l’imprimante sont définies dans les métadonnées d’appareil sur le PC local.

This example shows the FindAssociation method from the InkLevel.xaml.cs file:

async void FindAssociation(DeviceInformation deviceInfo, string containerId)
{

    // Specifically telling CreateFromIdAsync to retrieve the AppPackageFamilyName. 
    string packageFamilyName = "System.Devices.AppPackageFamilyName";
    string[] containerPropertiesToGet = new string[] { packageFamilyName };

    // CreateFromIdAsync needs braces on the containerId string.
    string containerIdwithBraces = "{" + containerId + "}";

    // Asynchronously getting the container information of the printer.
    PnpObject containerInfo = await PnpObject.CreateFromIdAsync(PnpObjectType.DeviceContainer, containerIdwithBraces, containerPropertiesToGet);

    // Printers could be associated with other device apps, only the ones with package family name
    // matching this app's is associated with this app. The packageFamilyName for this app will be found in this app's packagemanifest
    string appPackageFamilyName = "Microsoft.SDKSamples.DeviceAppForPrinters.CS_8wekyb3d8bbwe";
    var prop = containerInfo.Properties;

    // If the packageFamilyName of the printer container matches the one for this app, the printer is associated with this app.
    string[] packageFamilyNameList = (string[])prop[packageFamilyName];
    if (packageFamilyNameList != null)
    {
        for (int j = 0; j < packageFamilyNameList.Length; j++)
        {
            if (packageFamilyNameList[j].Equals(appPackageFamilyName))
            {
                AddToList(deviceInfo);
            }
        }
    }
}

Lorsqu’une association est trouvée, la FindAssociation méthode utilise la AddToList méthode pour ajouter l’ID d’appareil à une liste d’ID d’appareil associés. Ces ID sont stockés dans un comboBox nommé AssociatedPrinters.

This example shows the AddToList method from the InkLevel.xaml.cs file:

void AddToList(DeviceInformation deviceInfo)
{
    // Creating a new display item so the user sees the friendly name instead of the interfaceId.
    ComboBoxItem item = new ComboBoxItem();
    item.Content = deviceInfo.Properties["System.ItemNameDisplay"] as string;
    item.DataContext = deviceInfo.Id;
    AssociatedPrinters.Items.Add(item);

    // If this is the first printer to be added to the combo box, select it.
    if (AssociatedPrinters.Items.Count == 1)
    {
        AssociatedPrinters.SelectedIndex = 0;
    }
}

Étape 2 : Afficher l’état

La GetInkStatus méthode utilise un modèle asynchrone basé sur les événements pour demander des informations à partir de l’imprimante. Cette méthode utilise un ID d’appareil associé pour obtenir un contexte d’appareil qui peut être utilisé pour obtenir l’état de l’appareil. L’appel à la méthode lance la requête de l’appareil printHelper.SendInkLevelQuery() . Lorsque la réponse est retournée, la OnInkLevelReceived méthode est appelée et l’interface utilisateur est mise à jour.

This example shows the GetInkStatus and OnInkLevelReceived methods from the InkLevel.xaml.cs file:

void GetInkStatus(object sender, RoutedEventArgs e)
{
    if (AssociatedPrinters.Items.Count > 0)
    {
        // Get the printer that the user has selected to query.
        ComboBoxItem selectedItem = AssociatedPrinters.SelectedItem as ComboBoxItem;

        // The interfaceId is retrieved from the detail field.
        string interfaceId = selectedItem.DataContext as string;

        try
        {
            // Unsubscribe existing ink level event handler, if any.
            if (printHelper != null)
            {
                printHelper.OnInkLevelReceived -= OnInkLevelReceived;
                printHelper = null;
            }

            object context = Windows.Devices.Printers.Extensions.PrintExtensionContext.FromDeviceId(interfaceId);printHelper.SendInkLevelQuery()

            // Use the PrinterHelperClass to retrieve the bidi data and display it.
            printHelper = new PrintHelperClass(context);
            try
            {
                printHelper.OnInkLevelReceived += OnInkLevelReceived;
                printHelper.SendInkLevelQuery();

                rootPage.NotifyUser("Ink level query successful", NotifyType.StatusMessage);
            }
            catch (Exception)
            {
                rootPage.NotifyUser("Ink level query unsuccessful", NotifyType.ErrorMessage);
            }
        }
        catch (Exception)
        {
            rootPage.NotifyUser("Error retrieving PrinterExtensionContext from InterfaceId", NotifyType.ErrorMessage);
        }
    }
}

private void OnInkLevelReceived(object sender, string response)
{
    BidiOutput.Text = response;
}

La classe d’assistance d’impression s’occupe de l’envoi de la requête Bidi à l’appareil et de la réception de la réponse.

This example shows the SendInkLevelQuery method, and others, from the PrintHelperClass.cs file. Notez que seules certaines méthodes de classe d’assistance d’impression sont affichées ici. Téléchargez les paramètres d’impression et l’exemple de notifications d’impression pour afficher le code complet.

public void SendInkLevelQuery()
{
    printerQueue.OnBidiResponseReceived += OnBidiResponseReceived;

    // Send the query.
    string queryString = "\\Printer.Consumables";
    printerQueue.SendBidiQuery(queryString);
}

private void OnBidiResponseReceived(object sender, PrinterQueueEventArgs responseArguments)
{
    // Invoke the ink level event with appropriate data.
    dispatcher.RunAsync(
        Windows.UI.Core.CoreDispatcherPriority.Normal,
        () =>
        {
            OnInkLevelReceived(sender, ParseResponse(responseArguments));
        });
}

private string ParseResponse(PrinterQueueEventArgs responseArguments)
{
    if (responseArguments.StatusHResult == (int)HRESULT.S_OK)
        return responseArguments.Response;
    else
        return InvalidHResult(responseArguments.StatusHResult);
}

private string InvalidHResult(int result)
{
    switch (result)
    {
        case unchecked((int)HRESULT.E_INVALIDARG):
            return "Invalid Arguments";
        case unchecked((int)HRESULT.E_OUTOFMEMORY):
            return "Out of Memory";
        case unchecked((int)HRESULT.ERROR_NOT_FOUND):
            return "Not found";
        case (int)HRESULT.S_FALSE:
            return "False";
        case (int)HRESULT.S_PT_NO_CONFLICT:
            return "PT No Conflict";
        default:
            return "Undefined status: 0x" + result.ToString("X");
    }
}

Testing

Avant de pouvoir tester votre application d’appareil UWP, elle doit être liée à votre imprimante à l’aide de métadonnées d’appareil.

Vous avez besoin d’une copie du package de métadonnées d’appareil pour votre imprimante pour y ajouter les informations de l’application d’appareil. Si vous n’avez pas de métadonnées d’appareil, vous pouvez le générer à l’aide de l’Assistant Création de métadonnées d’appareil, comme décrit à l’étape 2 de la rubrique : Créer des métadonnées d’appareil pour votre application d’appareil UWP.

Les étapes suivantes créent votre application et installent les métadonnées de l’appareil.

1. Activez la signature de test.

   1. Démarrez l’Assistant Création de métadonnées d’appareil à partir de %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, en double-cliquant sur DeviceMetadataWizard.exe

   2. From the Tools menu, select Enable Test Signing.

2. Redémarrer l’ordinateur

3. Générez la solution en ouvrant le fichier de solution (.sln). Appuyez sur F7 ou accédez à Build-Build> Solution à partir du menu supérieur une fois l’exemple chargé.

4. Déconnectez et désinstallez l’imprimante. Cette étape est requise pour que Windows lise les métadonnées de l’appareil mises à jour la prochaine fois que l’appareil est détecté.

5. Modifiez et enregistrez les métadonnées de l’appareil. Pour lier l’application d’appareil à votre appareil, vous devez associer l’application d’appareil à votre appareil.

   Note

   Si vous n’avez pas encore créé vos métadonnées d’appareil, consultez l’étape 2 : Créer des métadonnées d’appareil pour votre application d’appareil UWP.

   1. Si l’Assistant Création de métadonnées d’appareil n’est pas encore ouvert, démarrez-le à partir de %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, en double-cliquant sur DeviceMetadataWizard.exe.

   2. Cliquez sur Modifier les métadonnées de l’appareil. Cela vous permet de modifier votre package de métadonnées d’appareil existant.

   3. In the Open dialog box, locate the device metadata package associated with your UWP device app. (It has a devicemetadata-ms file extension.)

   4. Dans la page Spécifier les informations de l’application d’appareil UWP , entrez les informations d’application du Microsoft Store dans la zone d’application d’appareil UWP . Cliquez sur Importer le fichier manifeste de l’application UWP pour entrer automatiquement le nom du package, le nom du serveur de publication et l’ID d’application UWP.

   5. If your app is registering for printer notifications, fill out the Notification handlers box. In Event ID, enter the name of the print event handler. In Event Asset, enter the name of the file where that code resides.

   6. When you're done, click Next until you get to the Finish page.

   7. Dans la page Vérifier le package de métadonnées de l’appareil , vérifiez que tous les paramètres sont corrects et activez la case à cocher Copier le package de métadonnées de l’appareil dans le magasin de métadonnées sur l’ordinateur local . Then click Save.

6. Reconnectez votre imprimante afin que Windows lit les métadonnées d’appareil mises à jour lorsque l’appareil est connecté.

Troubleshooting

Problème : Impossible de trouver l’imprimante lors de l’énumération d’appareils associés à l’application

Si votre imprimante est introuvable lors de l’énumération des imprimantes associées :

• Possible cause: Test signing is not turned on. Pour plus d’informations sur l’activation, consultez la section Débogage de cette rubrique.

• Possible cause: The app is not querying for the right Package Family Name. Vérifiez le nom de la famille de packages dans votre code. Open up package.appxmanifest in Microsoft Visual Studio and make sure that the package family name you are querying for matches the one in the Packaging tab, in the Package Family Name field.

• Possible cause: The device metadata is not associated with the Package Family Name. Utilisez l’Assistant Création de métadonnées d’appareil pour ouvrir les métadonnées de l’appareil et vérifier le nom de la famille de packages. Start the wizard from %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, by double-clicking DeviceMetadataWizard.exe.

Problème : Imprimante trouvée associée à l’application, mais ne peut pas interroger les informations Bidi

Si votre imprimante a été trouvée lors de l’énumération des imprimantes associées, mais une requête Bidi retourne une erreur...

• Possible cause: Wrong package family name. Vérifiez le nom de la famille de packages dans votre code. Open up package.appxmanifest in Visual Studio and make sure that the package family name you are querying for matches the one in the Packaging tab, in the Package Family Name field.

• Possible cause: Printer was installed using a v3 printer, rather than a v4 printer. Pour voir quelle version est installée, ouvrez PowerShell et tapez la commande suivante :

  get-printer | Select Name, {(get-printerdriver -Name $_.DriverName).MajorVersion}
  

Related topics

• Développement de pilotes d’impression v4
• Interfaces d’extension d’imprimante (pilote d’impression v4)
• Bidirectional Communications
• Prise en main des applications UWP
• Créer une application d’appareil UWP (guide pas à pas)
• Créer des métadonnées d’appareil pour une application d’appareil UWP (guide pas à pas)