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 a partir da interface do usuário moderna de um aplicativo de dispositivo UWP. Este tópico usa a versão em C# do exemplo de de configurações de impressão e notificações de impressão do para demonstrar como consultar o status da impressora e exibi-la. Para saber mais sobre os aplicativos de dispositivo UWP em geral, consulte Meet UWP device apps.

A versão em C# do exemplo de Configurações de impressão e notificações de impressão usa a página InkLevel.xaml para demonstrar como obter o status da impressora (neste caso, o nível de 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ões de impressora fornece uma maneira conveniente de acessar as interfaces de extensão de impressora do driver de impressão v4. Para obter mais informações, consulte a visão geral da biblioteca de extensões de impressora .

Prerequisites

Antes de começar:

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

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

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

4. Crie metadados de dispositivo para sua impressora que os associem ao seu aplicativo. Consulte Etapa 2: Criar metadados do dispositivo para obter mais informações 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 no Configurações de impressão e notificações de impressão exemplo.

   Note

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

Passo 1: Encontrar 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 método EnumerateAssociatedPrinters para pesquisar todas as impressoras que estão conectadas ao PC. 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 método FindAssociation, 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 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);
            }
        }
    }
}

Quando uma associação é encontrada, o método FindAssociation usa o método AddToList para adicionar a ID do dispositivo a uma lista de IDs de dispositivo associadas. Esses IDs são armazenados em uma ComboBox chamada 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 método GetInkStatus usa um padrão assíncrono baseado em eventos 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 método printHelper.SendInkLevelQuery() inicia a consulta do dispositivo. Quando a resposta retorna, o método OnInkLevelReceived é 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 encarrega-se de enviar a consulta Bidi para o dispositivo e receber a 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. Transfira o exemplo de definições de impressão e notificações de impressão de e 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 ser vinculado à 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 do dispositivo a ela. Se você não tiver metadados de dispositivo, poderá criá-los usando o Assistente para Criação de Metadados de 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 para Criação de Metadados de Dispositivo a partir do %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, clicando duas vezes em DeviceMetadataWizard.exe

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

2. Reinicie o computador

3. Crie a solução abrindo o arquivo de solução (.sln). Pressione F7 ou vá para Build ->Build Solution no menu no topo após o carregamento da amostra.

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

5. Edite e salve metadados do dispositivo. Para vincular o aplicativo de dispositivo ao seu dispositivo, você deve associá-lo ao seu dispositivo.

   Note

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

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

   2. Clique em Editar os 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 do aplicativo de dispositivo UWP. Clique em Importar arquivo de manifesto do aplicativo UWP para inserir automaticamente o Nome do pacote, Nome do editore 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 que todas as configurações estão corretas e selecione a caixa de seleção Copiar o pacote de metadados do dispositivo para o armazenamento de metadados no computador local. Then click Save.

6. Reconecte a impressora para que o Windows leia os metadados atualizados do dispositivo 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á-lo.

• Possible cause: The app is not querying for the right Package Family Name. Verifique o Nome da Família do Pacote no 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 Device Metadata Authoring Wizard para abrir os metadados do dispositivo e verificar o nome da família do pacote. Start the wizard from %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86, by double-clicking DeviceMetadataWizard.exe.

Problema: a impressora associada ao aplicativo foi encontrada, mas não é possível consultar as informações do Bidi

Se sua impressora foi encontrada ao enumerar as impressoras associadas, mas uma consulta Bidi retorna um erro...

• Possible cause: Wrong package family name. Verifique o Nome da Família do Pacote no 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

• Desenvolvimento de 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)