Expressões em um relatório paginado (Construtor de Relatórios)

Artigo
09/25/2024

Aplica-se a: SSRS (Construtor de Relatórios da Microsoft) Power BI Report Builder Report Designer no SQL Server Data Tools

As expressões são amplamente usadas em todos os relatórios paginados para recuperar, calcular, exibir, agrupar, classificar, filtrar, parametrizar e formatar dados.

Várias propriedades de item de relatório podem ser definidas para uma expressão. Expressões ajudam a controlar o conteúdo, o design e a interatividade do seu relatório. As expressões são escritas no Microsoft Visual Basic, salvas na definição de relatório e avaliadas pelo processador de relatório quando você executa o relatório.

Ao contrário de aplicativos como o Microsoft Office Excel, em que você trabalha com os dados diretamente em uma planilha, em um relatório você trabalha com expressões que são espaços reservados para os dados. Para ver os dados reais das expressões avaliadas, visualize o relatório. Quando você executa o relatório, o processador de relatório avalia cada expressão pois combina dados de relatório e elementos de layout de relatório, tais como tabelas e gráficos.

À medida que você cria um relatório, muitas expressões para itens de relatório são definidas. Por exemplo, quando você arrasta um campo do painel de dados para uma célula da tabela na superfície de design de relatório, o valor da caixa de texto é definido como uma expressão simples para o campo. Na figura a seguir, o painel Dados do Relatório exibe os campos do conjunto de dados ID, Name, SalesTerritory, Code e Sales. Três campos foram adicionados à tabela: [Name], [Code] e [Sales]. A notação [Name] na superfície de design representa a expressão subjacente =Fields!Name.Value.

rs_DataDesignandPreview

Quando você visualiza o relatório, o processador de relatório combina a região de dados da tabela com os dados reais da conexão de dados e exibe uma linha na tabela para cada linha no conjunto de resultados.

Para inserir expressões manualmente, selecione um item na superfície de design, e use menus de atalho e caixas de diálogo para definir as propriedades do item. Quando você visualiza o botão (fx) ou o valor <Expression> em uma lista suspensa, sabe que pode definir a propriedade como uma expressão. Para obter mais informações, confira Adicionar uma expressão (Construtor de Relatórios e SSRS).

Para desenvolver expressões complexas ou expressões que usam código personalizado ou assemblies personalizados, recomendamos o uso do Designer de Relatórios no SSDT (SQL Server Data Tools). Para obter mais informações, confira Referências a código personalizado e assemblies em expressões no Designer de Relatórios (SSRS).

Observação

Você pode criar e modificar arquivos de definição de relatório paginado (.rdl) no Construtor de Relatórios da Microsoft, Construtor de Relatórios do Power BI e no Designer de Relatórios no SQL Server Data Tools.

Compreendendo expressões simples e complexas

As expressões começam com um sinal de igual (=) e são escritas no Microsoft Visual Basic. Elas podem incluir uma combinação de constantes, operadores e referências para valores internos (campos, coleções e funções) e para o código externo ou personalizado.

Você pode usar expressões para especificar o valor de muitas propriedades de item de relatório. As propriedades mais comuns são valores para caixas de texto e texto do espaço reservado. Normalmente, se uma caixa de texto contiver só uma expressão, a expressão será o valor da propriedade de caixa de texto. Se uma caixa de texto contiver várias expressões, cada expressão será o valor de texto do espaço reservado na caixa de texto.

Por padrão, expressões aparecem na superfície de design de relatório como expressões simples ou expressões complexas.

Simples Uma expressão simples contém uma referência a um único item em uma coleção interna, como, por exemplo, um campo do conjunto de dados, um parâmetro ou um campo interno. Na superfície de design, uma expressão simples aparece entre colchetes. Por exemplo, [FieldName] corresponde à expressão subjacente =Fields!FieldName.Value. Expressões simples são criadas automaticamente à medida que você cria o layout de relatório e arrasta itens do painel de dados do relatório para a superfície de design. Para obter mais informações sobre os símbolos que representam coleções internas diferentes, consulte Compreendendo símbolos de prefixo de expressões simples.
Complexa Uma expressão complexa contém referências a várias referências internas, operadores e chamadas de função. Uma expressão complexa é exibida como <<Expr>> quando o valor de expressão inclui mais que uma referência simples. Para exibir a expressão, passe o mouse sobre ela e use a dica de ferramenta. Para editar a expressão, abra-a na caixa de diálogo Expressão .

A figura a seguir mostra expressões simples e complexas típicas para caixas de texto e texto do espaço reservado.

rs_ExpressionDefaultFormat

Para exibir valores de exemplo em vez de texto para expressões, aplique a formatação à caixa de texto ou texto do espaço reservado. A seguinte figura mostra a superfície de design de relatório alternada para mostrar valores de exemplo:

rs_ExpressionSampleValuesFormat

Para obter mais informações, confira Formatando texto e espaços reservados (Construtor de Relatórios e SSRS).

Compreendendo símbolos de prefixo em expressões simples

As expressões simples usam símbolos para indicar se a referência destina-se a um campo, a um parâmetro, a uma coleção interna ou à coleção ReportItems. A seguinte tabela mostra exemplos de texto de expressão e de exibição:

Item	Exemplo de texto de exibição	Exemplo de texto de expressão
Campos de conjunto de dados	`[Sales]` `[SUM(Sales)]` `[FIRST(Store)]`	`=Fields!Sales.Value` `=Sum(Fields!Sales.Value)` `=First(Fields!Store.Value)`
Parâmetros de relatório	`[@Param]` `[@Param.Label]`	`=Parameters!Param.Value` `=Parameters!Param.Label`
Campos internos	`[&ReportName]`	`=Globals!ReportName.Value`
Caracteres literais usados no texto para exibição	`\[Sales\]`	`[Sales]`

Escrevendo expressões complexas

Expressões podem incluir referências a funções, operadores, constantes, campos, parâmetros, itens das coleções internas, e ao código personalizado interno ou assemblies personalizados.

Observação

A seguinte tabela lista os tipos de referências que podem ser incluídos em uma expressão:

Referências	Descrição	Exemplo
Constantes	Descreve as constantes acessadas interativamente para propriedades que exigem valores de constantes, tais como cores de fontes.	`="Blue"`
Operadores	Descreve os operadores a serem usados para combinar referências em uma expressão. Por exemplo, o operador & é usado para concatenar cadeias de caracteres.	`="The report ran at: " & Globals!ExecutionTime & "."`
Coleções internas	Descreve as coleções internas que podem ser incluídas em uma expressão, tais como `Fields`, `Parameters`e `Variables`.	`=Fields!Sales.Value` `=Parameters!Store.Value` `=Variables!MyCalculation.Value`
Relatório interno e funções de agregação	Descreve as funções internas, tais como `Sum` ou `Previous`, que podem ser acessadas de uma expressão.	`=Previous(Sum(Fields!Sales.Value))`
Referências a código personalizado e assemblies em expressões no Designer de Relatórios (SSRS)	Descreve como você pode acessar as classes de CLR internas Math e Convert, outras classes de CLR, funções de biblioteca em tempo de execução do Visual Basic ou métodos de um assembly externo. Descreve como é possível acessar o código personalizado que é inserido no relatório, ou que é compilado e instalado como um assembly personalizado no cliente de relatório e no servidor de relatório.	`=Sum(Fields!Sales.Value)` `=CDate(Fields!SalesDate.Value)` `=DateAdd("d",3,Fields!BirthDate.Value)` `=Code.ToUSD(Fields!StandardCost.Value)`

Validando expressões

Quando você cria uma expressão para uma propriedade de item de relatório específica, as referências que podem ser incluídas em uma expressão dependem dos valores que a propriedade de item de relatório pode aceitar e do escopo em que a propriedade é avaliada. Por exemplo:

Por padrão, a expressão [Sum] calcula a soma de dados que estão no escopo quando a expressão é avaliada. Para uma célula de tabela, o escopo depende das associações de grupo de linhas e colunas. Para obter mais informações, confira Escopo das expressões para totais, agregações e coleções internas (Construtor de Relatórios e SSRS).
Para o valor de uma propriedade Font, o valor deve ser avaliado como o nome de uma fonte.
A sintaxe da expressão é validada no tempo de design. A validação do escopo da expressão ocorre quando você publica o relatório. Para a validação que depende dos dados reais, erros só podem ser detectados no tempo de execução. Algumas dessas expressões geram #Error como uma mensagem de erro no relatório renderizado. Para ajudar a determinar os problemas desse tipo de erro, use o Designer de Relatórios no SSDT (SQL Server Data Tools). O Designer de Relatórios fornece uma janela de Saída que fornece mais informações sobre esses erros.

Para obter mais informações, confira Referência de expressões (Construtor de Relatórios e SSRS).