Como exibir o status da impressora em um aplicativo de dispositivo UWP

No Windows 8.1, os usuários podem verificar o status da impressora na interface do usuário moderna de um aplicativo de dispositivo UWP. Este tópico usa a versão C# das configurações de impressão e o exemplo de notificações de impressão para demonstrar como consultar o status da impressora e exibi-lo. Para saber mais sobre aplicativos de dispositivo UWP em geral, consulte Conheça os aplicativos de dispositivo UWP.

A versão C# das configurações de impressão e do exemplo de notificações de impressão usa a página InkLevel.xaml para demonstrar como obter o status da impressora (nesse caso, o nível da tinta) e exibi-lo. Uma classe auxiliar de impressão é usada para criar um contexto de dispositivo (IPrinterExtensionContext) e executar as consultas de dispositivo. The PrinterHelperClass.cs file is in the DeviceAppForPrintersLibrary project and uses APIs defined in the PrinterExtensionLibrary project. A biblioteca de extensão da impressora fornece uma maneira conveniente de acessar as interfaces de extensão da impressora do driver de impressão v4. Para obter mais informações, consulte a visão geral da biblioteca de extensão da impressora.

Prerequisites

Antes de começar:

1. Verifique se a impressora está instalada usando um driver de impressão v4. Para obter mais informações, consulte Desenvolvendo drivers de impressão v4.

2. Configure seu computador de desenvolvimento. See Getting started for info about downloading the tools and creating a developer account.

3. Associe seu aplicativo à loja. Consulte a Etapa 1: Criar um aplicativo de dispositivo UWP para obter informações sobre isso.

4. Crie metadados de dispositivo para sua impressora que a associe ao seu aplicativo. Confira a Etapa 2: Criar metadados do dispositivo para saber mais sobre isso.

5. If you're writing your app with C# or JavaScript, add the PrinterExtensionLibrary and DeviceAppForPrintersLibrary projects to your UWP device app solution. Você pode encontrar cada um desses projetos na amostra de notificações de impressão e configurações de impressão .

   Note

   Como o C++ pode acessar o COM diretamente, os aplicativos C++ não exigem uma biblioteca separada para trabalhar com o contexto do dispositivo de impressora baseado em COM.

Etapa 1: Localizar a impressora

Antes que um contexto de dispositivo possa ser criado, o aplicativo precisa determinar a ID do dispositivo da impressora. Para fazer isso, o exemplo usa o EnumerateAssociatedPrinters método para pesquisar todas as impressoras anexadas ao computador. Em seguida, ele verifica o contêiner de cada impressora e procura uma associação comparando a propriedade PackageFamilyName de cada contêiner.

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

O FindAssociation método, chamado por EnumerateAssociatedPrinters, verifica se uma impressora está associada ao aplicativo atual. Em outras palavras, esse método verifica se o aplicativo é um aplicativo de dispositivo UWP. Essa associação existe quando o aplicativo e a impressora são definidos nos metadados do dispositivo no computador 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);
            }
        }
    }
}

Quando uma associação é encontrada, o FindAssociation método usa o AddToList método para adicionar a ID do dispositivo a uma lista de IDs de dispositivo associadas. Essas IDs são armazenadas em um ComboBox chamado 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;
    }
}

Etapa 2: Exibir o status

O GetInkStatus método usa um padrão assíncrono baseado em evento para solicitar informações da impressora. Esse método usa uma ID de dispositivo associada para obter um contexto de dispositivo que pode ser usado para obter o status do dispositivo. A chamada para o printHelper.SendInkLevelQuery() método inicia a consulta do dispositivo. Quando a resposta é retornada, o OnInkLevelReceived método é chamado e a interface do usuário é atualizada.

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

A classe auxiliar de impressão cuida do envio da consulta Bidi para o dispositivo e do recebimento da resposta.

This example shows the SendInkLevelQuery method, and others, from the PrintHelperClass.cs file. Observe que apenas alguns dos métodos de classe auxiliar de impressão são mostrados aqui. Baixe as configurações de impressão e o exemplo de notificações de impressão para ver o código completo.

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

Antes de testar seu aplicativo de dispositivo UWP, ele deve estar vinculado à sua impressora usando metadados do dispositivo.

Você precisa de uma cópia do pacote de metadados do dispositivo para sua impressora, para adicionar as informações do aplicativo de dispositivo a ele. Se você não tiver metadados de dispositivo, poderá criá-lo usando o Assistente de Criação de Metadados do Dispositivo , conforme descrito no tópico Etapa 2: Criar metadados de dispositivo para seu aplicativo de dispositivo UWP.

As etapas a seguir criam seu aplicativo e instalam os metadados do dispositivo.

1. Habilite a assinatura de teste.

   1. Inicie o Assistente de Criação de Metadados do Dispositivo%ProgramFiles(x86)%\Windows Kits\8.1\bin\x86 clicando duas vezes DeviceMetadataWizard.exe

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

2. Reinicializar o computador

3. Crie a solução abrindo o arquivo de solução (.sln). Pressione F7 ou vá para a Solução Build-Build> no menu superior depois que o exemplo for carregado.

4. Desconecte e desinstale a impressora. Essa etapa é necessária para que o Windows leia os metadados do dispositivo atualizados na próxima vez que o dispositivo for detectado.

5. Editar e salvar metadados do dispositivo. Para vincular o aplicativo de dispositivo ao seu dispositivo, você deve associar o aplicativo de dispositivo ao seu dispositivo.

   Note

   Se você ainda não criou os metadados do dispositivo, confira a Etapa 2: Criar metadados de dispositivo para seu aplicativo de dispositivo UWP.

   1. Se o Assistente de Criação de Metadados do Dispositivo ainda não estiver aberto, inicie-o de%ProgramFiles(x86)%\Windows Kits\8.1\bin\x86 clicando duas vezes DeviceMetadataWizard.exe.

   2. Clique em Editar Metadados do Dispositivo. Isso permitirá que você edite o pacote de metadados do dispositivo existente.

   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. Na página Especificar informações do aplicativo de dispositivo UWP , insira as informações do aplicativo da Microsoft Store na caixa de aplicativo do dispositivo UWP . Clique em Importar arquivo de manifesto do aplicativo UWP para inserir automaticamente o nome do pacote, o nome do publicador e a ID do aplicativo 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. Na página Revisar o pacote de metadados do dispositivo , verifique se todas as configurações estão corretas e selecione Copiar o pacote de metadados do dispositivo para o repositório de metadados na caixa de seleção do computador local . Then click Save.

6. Reconecte sua impressora para que o Windows leia os metadados do dispositivo atualizados quando o dispositivo estiver conectado.

Troubleshooting

Problema: não é possível localizar a impressora ao enumerar dispositivos associados ao aplicativo

Se a impressora não for encontrada ao enumerar as impressoras associadas:

• Possible cause: Test signing is not turned on. Consulte a seção Depuração neste tópico para obter informações sobre como ativá-la.

• Possible cause: The app is not querying for the right Package Family Name. Verifique o Nome da Família de Pacotes em seu código. 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. Use o Assistente de Criação de Metadados do Dispositivo para abrir os metadados do dispositivo e verificar o nome da família de pacotes. Start the wizard from %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, by double-clicking DeviceMetadataWizard.exe.

Problema: encontrada impressora associada ao aplicativo, mas não pode consultar informações do Bidi

Se a impressora foi encontrada ao enumerar as impressoras associadas, mas uma consulta Bidi retornará um erro...

• Possible cause: Wrong package family name. Verifique o Nome da Família de Pacotes em seu código. 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. Para ver qual versão está instalada, abra o PowerShell e digite o seguinte comando:

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

Related topics

• Desenvolvendo drivers de impressão v4
• Interfaces de Extensão de Impressora (Driver de Impressão v4)
• Bidirectional Communications
• Introdução aos aplicativos UWP
• Criar um aplicativo de dispositivo UWP (guia passo a passo)
• Criar metadados de dispositivo para um aplicativo de dispositivo UWP (guia passo a passo)