• Artigo

Usando o controle RSClientPrint em aplicativos personalizados

O controle ActiveX Microsoft, RSPrintClient, oferece impressão do lado cliente para relatórios exibidos em Visualizador de HTML. Ele fornece uma caixa de diálogo Imprimir para que um usuário possa iniciar um trabalho de impressão, visualizar um relatório, especificar páginas a serem impressas e alterar as margens. Durante uma operação de impressão do lado cliente, o servidor de relatório renderiza o relatório na extensão de renderização Image (EMF) e usa os recursos de impressão do sistema operacional para criar o trabalho de impressão e para enviá-lo para uma impressora.

A impressão do lado cliente oferece uma forma de controlar e de aprimorar a qualidade de uma cópia impressa de um relatório HTML ao esquivar-se das configurações de impressão do navegador do computador do usuário e usar as dimensões de página, as margens, o cabeçalho e o texto de rodapé do relatório para criar a saída de impressão. O controle de impressão lê valores de propriedade do relatório para definir o tamanho de página e as margens.

Os desenvolvedores que desejam habilitar o recurso de impressão do lado cliente em barras de ferramentas de terceiros ou em visualizadores poderão acessar o controle ActiveX por meio do objeto COM RSClientPrint. O controle pode ser distribuído livremente. A lista a seguir oferece recomendações para o uso do controle:

  • Use o controle para melhorar a impressão de relatórios baseados na Web. Você pode especificar o objeto em qualquer das linguagens de programação compatíveis com o Microsoft.NET Framework ou em um script. O controle não foi criado para os aplicativos Microsoft Windows Forms.

  • Copie o arquivo .cab arquivo dos arquivos de programa do Reporting Services e adicione-o à sua base de código de aplicativo personalizado.

  • Use uma marca <OBJECT> para especificar o controle.

  • Especifique uma URL relativa ou totalmente qualificada para o arquivo .cab no atributo OBJECT CODEBASE.

  • Especifique as suas próprias informações de versão de aplicativo para o arquivo .cab para rastrear qual versão será usada em seu aplicativo.

  • Examine os tópicos dos Manuais Online sobre a renderização de Image (EMF) para compreender como as páginas são renderizadas para a visualização de impressão e a saída.

Visão geral de RSPrintClient

O controle exibe uma caixa de diálogo de impressão personalizada que fornece recursos de suporte comuns a outras caixas de diálogo de impressão, inclusive visualização de impressão, seleções de páginas para definir páginas e intervalos específicos, margens de páginas e orientação de página. O controle é empacotado como um arquivo CAB. O texto da caixa de diálogo Imprimir foi localizado para todos os idiomas suportados no SQL Server. O controle ActiveX RSPrintClient usa a extensão de renderização Image (EMF) para imprimir o relatório. As informações de dispositivo EMF a seguir são usadas: StartPage, EndPage, MarginBottom, MarginLeft, MarginTop, MarginRight, PageHeight e PageWidth. Outras configurações de informações de dispositivo para renderização de imagens não são suportadas.

Suporte ao idioma

O controle de impressão fornece texto de interface do usuário em idiomas diferentes e aceita valores de entrada calibrados para diferentes sistemas de medidas. O idioma e o sistema de medidas usados são determinados pelas propriedades Culture e UICulture. Ambas as propriedades aceitam valores LCID. Se você especificar um LCID para um idioma que seja uma variação de um idioma suportado, obterá o idioma correspondente mais próximo. Se você especificar um LCID que não seja suportado e para o qual não haja um LCID correspondente próximo, obterá o inglês (Estados Unidos).

Usando o RSPrintClient em código

O objeto RSClientPrint é usado para a obtenção de acesso programaticamente ao controle ActiveX e a seus métodos e propriedades. O controle fornece uma caixa de diálogo modal para a visualização de impressão.

Especificando valores padrão

Você pode inicializar a caixa de diálogo Imprimir com valores de margem e de página do relatório. Por padrão, a caixa de diálogo Imprimir é inicializada com valores obtidos da definição de relatório. Você pode usar os padrões ou especificar valores diferentes definindo as propriedades no objeto.

Todas as dimensões são definidas em milímetros. A conversão de medidas ocorrerá em tempo de execução se Culture e UICulture forem definidas para localidades que não usam dimensões métricas.

Para entender quais valores serão usados para dimensões de página e de margens, use o método GetProperties para recuperar os valores padrão:

  • PageHeight e PageWidth especificam a altura e a largura de página padrão. Quando o controle de impressão é iniciado, esses valores de propriedade são usados para selecionar o tamanho de papel mais próximo disponível para a impressora atualmente selecionada. Se PageWidth for maior do que PageHeight, a orientação será definida como Paisagem. Caso contrário, será definida como Retrato.

  • LeftMargin, RightMargin, TopMargin e BottomMargin são definidas como 12,2 milímetros por padrão.

Essas propriedades são armazenadas na coleção de propriedades Item no servidor de relatório. Os valores serão substituídos sempre que uma definição de relatório for atualizada.

Propriedades RSPrintClient

Propriedade

Tipo

RW

Padrão

Descrição

MarginLeft

Double

RW

configuração de relatório

Obtém ou define a margem esquerda. O valor padrão, caso não seja definido pelo desenvolvedor ou especificado no relatório, é 12,2 milímetros.

MarginRight

Double

RW

configuração de relatório

Obtém ou define a margem direita. O valor padrão, caso não seja definido pelo desenvolvedor ou especificado no relatório, é 12,2 milímetros.

MarginTop

Double

RW

configuração de relatório

Obtém ou define a margem superior. O valor padrão, caso não seja definido pelo desenvolvedor ou especificado no relatório, é 12,2 milímetros.

MarginBottom

Double

RW

configuração de relatório

Obtém ou define a margem inferior. O valor padrão, caso não seja definido pelo desenvolvedor ou especificado no relatório, é 12,2 milímetros.

PageWidth

Double

RW

configuração de relatório

Obtém ou define a largura da página. O valor padrão, caso não seja definido pelo desenvolvedor ou pela definição de relatório, é 215,9 milímetros.

PageHeight

Double

RW

configuração de relatório

Obtém ou define a altura da página. O valor padrão, caso não seja definido pelo desenvolvedor ou pela definição de relatório, é 279,4 milímetros.

Culture

Int32

RW

Localidade do navegador

Especifica o LCID (identificador de localidade). Este valor determina a unidade de medida para a entrada de usuário. Por exemplo, se um usuário digitar 3, o valor será medido em milímetros caso o idioma seja o francês ou em polegadas se o idioma for o inglês (Estados Unidos). Os valores válidos incluem: 1028, 1031, 1033, 1036, 1040, 1041, 1042, 2052, 3082.

UICulture

String

RW

Cultura do cliente

Especifica localização da cadeia de caracteres da caixa de diálogo. O texto da caixa de diálogo Imprimir está localizado para estes idiomas: chinês simplificado, chinês tradicional, inglês, francês, alemão, italiano, japonês, coreano e espanhol. Os valores válidos incluem: 1028, 1031, 1033, 1036, 1040, 1041, 1042, 2052, 3082.

Authenticate

Boolean

RW

False

Especifica se o controle emite um comando GET para o servidor de relatório para iniciar uma conexão de impressão fora de sessão.

Quando definir a propriedade Authenticate

Quando você imprimir de uma sessão do navegador, não precisará definir a propriedade Authenticate. No contexto de uma sessão ativa, todas as solicitações do controle de impressão para o servidor de relatório serão manipuladas por meio do navegador. O navegador define as variáveis de sessão necessárias para a comunicação com o servidor de relatório.

Se você imprimir fora de sessão (por exemplo, o envio de um relatório diretamente para a impressora, sem que ele tenha sido aberto), o controle de impressão terá de emitir uma solicitação GET HTTP para configurar a sessão com o servidor de relatório. Para emitir a solicitação GET, defina Authenticate como True.

Você só precisará emitir a solicitação GET se estiver usando a segurança integrada do Windows ou a autenticação Básica. Se você estiver usando a autenticação de formulários, a propriedade Authenticate será ignorada. O código do seu aplicativo precisa definir a sessão e autenticar o usuário usando a extensão de segurança personalizada fornecida por você. Se você estiver usando a autenticação de formulários, não se esqueça de definir o valor de expiração no cookie de autenticação como um valor que preserve sessões por um intervalo razoável. Se o valor for muito baixo, será solicitado que os usuários forneçam credenciais de logon sempre que o cookie expirar.

Método de impressão RSPrintClient

O objeto RSClientPrint dá suporte ao método Print usado para iniciar a caixa de diálogo Imprimir. O método Print tem os argumentos a seguir.

Argumento

E/S

Tipo

Descrição

ServerPath

Entrada

String

Especifica o diretório virtual de servidor de relatório (por exemplo, https://adventure-works/reportserver).

ReportPathParameters

Entrada

String

Especifica o nome completo para o relatório no namespace da pasta do servidor de relatório, incluindo os parâmetros. Os relatórios são recuperados por meio do acesso à URL. Por exemplo: "/AdventureWorks Sample Reports/Resumo de Vendas do Funcionário&EmpID=1234"

ReportName

Entrada

String

O nome curto do relatório (no exemplo anterior, o nome curto é Resumo de Vendas do Funcionário). Ele será exibido na caixa de diálogo Imprimir e na fila de impressão.

Exemplo

O exemplo de HTML a seguir mostra como especificar o arquivo .cab, o método Print e as propriedades em JavaScript:

<BODY onload="Print()">

<OBJECT ID="RSClientPrint" CLASSID="CLSID:FA91DF8D-53AB-455D-AB20-F2F023E498D3" CODEBASE="<URL to the .CAB file>#Version=<your application version information>" VIEWASTEXT></OBJECT>

<script language="javascript">

function Print()

{

RSClientPrint.MarginLeft = 12.7;

RSClientPrint.MarginTop = 12.7;

RSClientPrint.MarginRight = 12.7;

RSClientPrint.MarginBottom = 12.7;

RSClientPrint.Culture = 1033;

RSClientPrint.UICulture = 9;

RSClientPrint.Print('https://localhost/rtm', '%2fEmployee_Sales_Summary&ReportMonth=6&ReportYear=2004&EmpID=20', 'Employee_Sales_Summary')

}

</script>

</BODY>