Utilisation de collections globales dans les expressions (Reporting Services)

Article
12/15/2008

Mis à jour : 14 avril 2006

Reporting Services fournit les collections globales suivantes auxquelles vous pouvez faire référence à partir d'expressions : DataSources, DataSets, Fields, Globals, Parameters, ReportItems et User. Pour faire référence à une collection à partir d'une expression, vous pouvez utiliser une syntaxe Visual Basic standard pour un élément au sein d'une collection. La liste suivante fournit des exemples de cette syntaxe :

Collection!ObjectName.Property ou Collection!ObjectName("Property")
=Fields!Sales.Value
=Fields!Sales("Value")
Collection("ObjectName").Property
=Fields("Sales").Value
Collection("Member")
=User("Language")
Collection.Member
=User.Language

Récapitulatif des collections globales

Le tableau suivant décrit chaque collection globale et indique quand vous pouvez faire référence à la collection à partir d'une expression. Chaque collection globale est décrite dans une rubrique distincte plus loin dans cette section.

Collection globale	Exemple	Description
Fields	`=Fields!Sales.Value`	Représente la collection des champs du dataset qui sont disponibles pour le rapport. Disponibles après extraction des données d'une source de données dans un dataset.
ReportItems	`=ReportItems("Textbox1").Value`	Représente la collection des zones de texte pour l'élément de rapport, par exemple les zones de texte contenues dans une région de données de tableau, un en-tête de page ou un pied de page. Disponibles durant le traitement des rapports.
Globals	`=Globals.ReportName`	Représente les variables globales utilisables pour des rapports, par exemple le nom du rapport ou le numéro de page. Toujours disponible.
Parameters	`=Parameters("ReportMonth").Value` - ou - `=Parameters!ReportYear.Value`	Représente la collection des paramètres de rapport, chacun pouvant correspondre à une valeur unique ou à plusieurs valeurs. Non disponible tant que l'initialisation du traitement n'est pas terminée. Lorsque vous créez des paramètres de requête, ils sont automatiquement ajoutés à la collection de paramètres du rapport.
User	`=User.UserID` - ou - `User.Language`	Représente une collection de données sur l'utilisateur exécutant le rapport, par exemple le paramètre de langue ou l'ID utilisateur. Toujours disponible. `User!UserID` est souvent utilisé pour filtrer les résultats des rapports.
DataSources	`=DataSources("AdventureWorks").Type`	Représente la collection des sources de données référencées à partir du corps d'un rapport. N'inclut pas les sources de données utilisées uniquement dans les en-têtes ou les pieds de page. Non disponible dans l'aperçu local.
DataSets	`=DataSets("TopEmployees").CommandText`	Représente la collection de sources de données référencées à partir du corps d'une définition de rapport. N'inclut pas les sources de données utilisées uniquement dans les en-têtes ou les pieds de page. Non disponible dans l'aperçu local.

Les membres des collections Globals et Users retournent des valeurs de type Variant. Si vous souhaitez utiliser une variable globale dans une expression nécessitant un type de données spécifique, vous devez en premier lieu effectuer le cast de la variable Par exemple, pour convertir la variante de temps d'exécution en format de date, utilisez CDate(Globals!ExecutionTime). Pour obtenir d'autres d'exemples, consultez Exemples d'expressions dans Reporting Services.

Fields

Chaque dataset dans un rapport contient une collection Fields. Il s'agit de la collection des champs que vous voyez lorsque vous développez un nœud de dataset dans la fenêtre Datasets. La collection Fields est généralement utilisée pour afficher des données dans les zones de texte d'un rapport, mais elle peut également être employée dans d'autres éléments de rapport, propriétés et fonctions. Les noms de champs doivent être uniques au sein d'une collection, mais le même nom de champ peut être présent dans plusieurs collections.

Certaines extensions de traitement des données identifient automatiquement la collection de champs à partir de la requête que vous définissez pour un dataset. Lorsque vous cliquez sur le bouton Actualiser les champs de la barre d'outils, les modifications sont enregistrées dans la définition de rapport et la fenêtre Datasets est mise à jour pour afficher ces modifications. Pour modifier les définitions de champ, ouvrez le Concepteur de rapports en mode Données, sélectionnez le dataset pour ouvrir la boîte de dialogue Dataset, puis cliquez sur l'onglet Champs. Pour ajouter un champ calculé, cliquez avec le bouton droit sur le dataset dans la fenêtre Datasets pour ouvrir la boîte de dialogue Ajouter un nouveau champ et tapez un nom. Cliquez ensuite sur Champ calculé et entrez l'expression.

Lors du traitement consécutif de chacun des éléments du rapport, la collection Fields associée à l'élément de rapport en cours de traitement est liée à la source de données sous-jacente. Les données retournées pour un champ spécifique peuvent être une valeur unique ou une valeur attribuée à chaque ligne du dataset lors du traitement du rapport. Le renvoi d'une valeur unique ou de plusieurs valeurs dépend du type de l'élément de rapport contenant la référence de champ. Les références d'une région de données (table, matrice, liste ou graphique) retournent une valeur pour chaque ligne du dataset. Les références n'appartenant à aucune région de données retournent une valeur unique.

Lorsque vous utilisez une fonction de rapport d'agrégation pour traiter la collection de champs d'un dataset, vous incluez un paramètre scope qui spécifie le dataset. Pour vérifier l'association d'un élément de rapport avec un dataset, sélectionnez le rapport et affichez ses propriétés. Pour plus d'informations sur les fonctions de rapport et le paramètre d'étendue, consultez Utilisation de fonctions de rapport dans des expressions (Reporting Services).

Par défaut, les éléments de la collection Fields disposent de deux propriétés : Value et IsMissing. Lorsque vous faites glisser un champ de la fenêtre Datasets vers un élément du rapport dans la mise en page de ce dernier, le contenu de l'élément en question est défini sur la propriété Value du champ par défaut. Dans le cas d'une région de données, la valeur de chaque ligne du dataset est définie sur =Fields!FieldName.Value. Le contenu d'un élément de rapport autre qu'une région de données est défini sur une valeur unique, telle que =First(Fields!FieldName.Value).

La propriété IsMissing indique si un champ défini pour un dataset figure dans les champs extraits de la source de données. Ce champ peut être testé dans une expression de champ à l'aide de Visual Basic. La propriété Value pour les champs manquants a une valeur NULL (Nothing en Visual Basic). L'exemple suivant, s'il est placé dans la zone de texte de l'élément de rapport dans laquelle vous souhaitez afficher les données de champ, vous montre comment tester et rechercher un champ manquant :

=IIF(Fields!FieldName.IsMissing, "Field was not returned by query", Fields!FieldName.Value))

Du fait que la fonction IIF de Visual Basic évalue tous les éléments d'une instruction avant de retourner le résultat, les références à un champ manquant peuvent provoquer des erreurs de traitement. L'exemple ci-dessous vous explique comment générer des appels de fonction Visual Basic faisant référence à un champ susceptible d'être manquant :

=IIF(Sum(Fields!FieldName.Value) IS NOTHING, 0, Sum(Fields!FieldName.Value))

Lorsque vous créez une expression faisant référence à un champ à l'aide de l'éditeur d'expressions, vous pouvez sélectionner la collection Fields dans le premier volet et consulter la liste des champs disponibles dans le dernier volet. La figure suivante affiche le champ FirstName d'un dataset nommé Employees.

Boîte de dialogue Modifier l'expression avec Intellisense

Notez la liste des propriétés disponibles dans la fenêtre IntelliSense. Cette liste comprend les propriétés par défaut Value et IsMissing. Les propriétés restantes sont des propriétés de champ étendues prédéfinies et prises en charge par d'autres extensions de traitement des données.

Propriétés de champ étendues

Les propriétés de champ étendues sont des propriétés supplémentaires définies dans un champ par l'extension de traitement des données. Un sous-ensemble de propriétés de champ étendues est prédéfini. Les propriétés prédéfinies sont des propriétés de champ fréquemment utilisées. Le champ Key et le champ UniqueName en sont des exemples typiques. Ces propriétés prédéfinies apparaissent dans la liste IntelliSense et peuvent être référencées à l'aide de la syntaxe de collection Fields!FieldName.Property. Une extension de traitement des données peut choisir de tirer parti des propriétés prédéfinies en optimisant les requêtes qui intègrent cette syntaxe.

Vous pouvez également vous référer à d'autres propriétés de champ étendues prises en charge par une extension de traitement des données spécifique. Ces propriétés n'apparaissent pas dans la fenêtre Expressions mais peuvent être déterminées en analysant une source de données par le biais d'une extension de traitement des données enregistrée et de son Concepteur de requêtes associé. Toutes les propriétés de champ étendues peuvent être référencées à l'aide de la syntaxe de collection Fields!FieldName("Property").

Si un fournisseur de données ne prend pas en charge les propriétés de champ étendues ou si le champ est introuvable lors de l'exécution de la requête, la valeur attribuée à la propriété est null (Nothing dans Visual Basic) pour les propriétés de type String et Object, et zéro (0) pour les propriétés de type Integer.

Si l'extension de données fournit des propriétés de champ personnalisées, ces propriétés sont visibles dans la liste déroulante de l'Éditeur d'expression pour tous les champs du dataset, qu'un champ prenne ou non en charge cette propriété. Si vous ajoutez une référence à une propriété qui n'est pas prise en charge pour ce champ, la référence prend la valeur null (Nothing dans Visual Basic). Pour obtenir des exemples de fournisseurs prenant en charge les propriétés de champ étendues, consultez Définition de datasets de rapport pour les données multidimensionnelles et les données de prédiction d'exploration de données d'Analysis Services et Définition de datasets de rapport pour les données multidimensionnelles d'un système SAP NetWeaver BI.

Globals

La collection Globals comprend les variables globales du rapport. Le tableau ci-dessous décrit les membres de la collection Globals.

Membre	Type	Description
ExecutionTime	DateTime	Date et heure du début de l'exécution du rapport.
PageNumber	Integer	Numéro de la page actuelle. Ce numéro peut uniquement être utilisé dans les en-têtes et les pieds de page.
ReportFolder	String	Chemin complet au dossier contenant le rapport. Ce chemin n'inclut pas l'URL du serveur de rapports.
ReportName	String	Nom du rapport tel qu'il est stocké dans la base de données du serveur de rapports.
ReportServerUrl	String	URL du serveur de rapports sur lequel le rapport est en cours d'exécution.
TotalPages	Integer	Nombre total de pages du rapport. Ce numéro peut uniquement être utilisé dans les en-têtes et les pieds de page.

Voici quelques exemples de variables globales :

Cette expression, placée dans une zone de texte dans le pied de page d'un rapport, indique le numéro de la page actuelle ainsi que le nombre total de pages du rapport :
=Globals.PageNumber & " of " & Globals.TotalPages
Cette expression fournit le nom du rapport ainsi que les date et heure de son exécution. Le format de date/heure est déterminé par la chaîne de formatage Microsoft .NET Framework pour la date courte :
=Globals.ReportName & ", dated " & Format(Globals.ExecutionTime, "d")

Parameters

La collection Parameters comprend les objets Parameter du rapport. Il est possible de passer des paramètres aux requêtes, de les utiliser dans des filtres ou dans d'autres fonctions qui modifient l'aspect et le contenu du rapport en conséquence. Lorsque vous définissez des paramètres de requête, ils sont automatiquement ajoutés à la collection de paramètres du rapport. Le tableau suivant décrit les propriétés définies sur un Parameter: Count, IsMultiValue, Value et Label.

Propriété	Description
Count	Entier qui indique le nombre de paramètres dans la collection.
IsMultiValue	Valeur booléenne qui indique que ce paramètre a un ensemble de valeurs.
Value	Valeur du paramètre. Pour un paramètre à plusieurs valeurs, Value retourne un tableau d'objets.
Label	Étiquette conviviale pour le paramètre. Si aucune étiquette n'est spécifiée, la valeur de la propriété Label est la même que celle de la propriété Value. Si plusieurs Label sont associées à la même Value, la première Label qui correspond est employée. Pour un paramètre à plusieurs valeurs, Label retourne un tableau d'objets.

Il est possible d'accéder aux paramètres à l'aide de la syntaxe de propriété ou de la syntaxe de collection. L'expression suivante montre comment accéder à chaque membre de la collection Parameters et, lorsqu'elle est placée dans une zone de texte d'un élément de rapport, affiche le contenu du paramètre ProductSubCategory.

="IsMultiValue: " & Parameters!ProductSubCategory.IsMultiValue.ToString() 
& " Count:" & Parameters!ProductSubCategory.Count & " Values: " 
& Join(Parameters!ProductSubCategory.Value,", ") & " Labels: " 
& Join(Parameters!ProductSubCategory.Label,", ")

Pour plus d'informations, consultez Utilisation de paramètres dans Reporting Services.

ReportItems

La collection ReportItems comprend les zones de texte du rapport. Ses éléments ont une seule propriété : Value. La valeur d'un élément ReportItems peut être utilisée pour afficher ou pour calculer des données provenant d'un autre champ du rapport. Pour accéder à la valeur de la zone de texte actuelle, vous pouvez utiliser l'entité Me.Value globale intégrée Visual Basic ou simplement Value. Dans les fonctions de rapport telles que First et les fonctions d'agrégation, il convient toutefois d'utiliser la syntaxe complète.

Par exemple :

Cette expression, placée dans une zone de texte, affiche la valeur d'une zone de texte ReportItem nommée Textbox1 :
=ReportItems("Textbox1").Value
Cette expression, placée dans la propriété Couleur d'une zone de texte ReportItem, affiche le texte en noir lorsque la valeur est > 0, sinon en rouge :
=iif(Me.Value > 0,"Black","Red")
Cette expression, placée dans une zone de texte dans l'en-tête ou le pied de page, affiche la première valeur par page du rapport rendu pour une zone de texte nommée LastName :
=First(ReportItems("LastName").Value)

User

La collection User contient des données relatives à l'utilisateur qui exécute le rapport. Vous pouvez utiliser cette collection pour filtrer les données qui apparaissent dans un rapport, par exemple pour montrer uniquement les données de l'utilisateur actuel ou inclure l'ID utilisateur dans un titre de rapport. L'expression suivante, placée dans une zone de texte, combine du texte statique à des données utilisateur variables :

=Globals!ReportName & " for " & User!UserID

Le tableau ci-dessous décrit les membres de la collection User.

Membre	Type	Description
Language	String	Langue de l'utilisateur qui exécute le rapport. Par exemple, `en-US`.
UserID	String	Identificateur de l'utilisateur qui exécute le rapport. Si vous utilisez l'authentification Windows, cette valeur est le compte de domaine de l'utilisateur actuel. La valeur est déterminée par l'extension de sécurité de Reporting Services, qui peut utiliser l'authentification Windows ou une authentification personnalisée.

Dans certains cas, les rapports qui comprennent la variable User!UserID ne parviennent pas à afficher les données du rapport qui sont spécifiques à l'utilisateur qui affiche le rapport. Cette erreur se produit lorsque les conditions suivantes sont réunies :

Le rapport doit être une capture instantanée d'exécution de rapport ou une capture instantanée d'historique de rapport.
Le rapport doit être accessible par programme au moyen de méthodes SOAP ou par le biais de l'adresse URL du rapport.

Lorsque cette erreur se produit, les informations sur le profil utilisateur contenues dans la capture instantanée du rapport peuvent être basées sur l'un des éléments suivants :

L'identité de l'utilisateur ayant créé la capture instantanée du rapport.
Le compte sous lequel s'exécute le serveur de rapports si la capture instantanée a été créée par le serveur de rapports dans le cadre d'une opération planifiée.

Important :
L'échec de la mise à jour d'une capture instantanée de rapport basée sur les informations de profil utilisateur engendre l'utilisation de données incorrectes et introduit un risque de sécurité si des données confidentielles ou sensibles sont incluses dans la capture instantanée.

Des incidents de profil utilisateur se produisent uniquement pour les captures instantanées de rapport qui sont ouvertes au moyen d'appels SOAP ou par le biais de l'adresse URL de la capture instantanée du rapport. User!UserID est entièrement fonctionnel pour les rapports exécutés sur demande et pour toutes les captures instantanées de rapport qui sont ouvertes à partir du Gestionnaire de rapports. Pour plus d'informations sur l'appel des captures instantanées de rapports à partir de méthodes de service Web et d'un accès URL, consultez Using a URL to Access Report Server Items et Identifying Execution State.

DataSources

La collection DataSources représente les sources de données référencées dans la définition d'un rapport publié. Les valeurs obtenues pour ces paramètres en mode aperçu risquent d'être différentes de celles obtenues lors du déploiement et de la visualisation d'un rapport publié.

Le tableau ci-dessous décrit les variables de la collection DataSources.

Variable	Type	Description
DataSourceReference	String	Chemin complet de la source de données sur le serveur de rapports. Par exemple, `/DataSources/AdventureWorks.`
Type	String	Type du fournisseur de données pour la source de données. Par exemple, `SQL`.

DataSets

La collection DataSets représente les datasets référencés dans une définition de rapport. Cette collection globale est rarement utilisée directement dans des rapports mais les Concepteurs de rapports peuvent l'employer pour accéder à la commande de requête utilisée pour récupérer les données d'une source de données pour chaque dataset.

Le tableau ci-dessous décrit les membres de la collection DataSets.

Membre	Type	Description
CommandText	String	Pour les sources de données de base de données, il s'agit de la requête employée pour récupérer des données à partir de la source de données. Si la requête est une expression, elle correspond à l'expression évaluée.
RewrittenCommandText	String	Valeur CommandText développée du fournisseur de données. Elle est généralement utilisée pour les rapports dont les paramètres de requête sont mappés aux paramètres du rapport. Le fournisseur de données définit cette propriété lors du développement des références de paramètre du texte de commande dans les valeurs de constante sélectionnées pour les paramètres de rapport mappés.

Voir aussi

Historique des modifications

Version	Historique
14 avril 2006	Contenu modifié : Développement du contenu de la section consacrée à la collection Fields.
5 décembre 2005	Nouveau contenu : Ajout des collections Datasets et DataSources. Contenu modifié : Exemples de syntaxe globale modifiés.

14 avril 2006

Contenu modifié :

Développement du contenu de la section consacrée à la collection Fields.

5 décembre 2005

Nouveau contenu :

Ajout des collections Datasets et DataSources.