Procédure : Créer des éditeurs pour les rapports des services PerformancePoint Services
Dernière modification : mardi 30 août 2011
Dans les Services PerformancePoint dans Microsoft SharePoint Server 2010, les éditeurs personnalisés permettent aux utilisateurs de définir des propriétés sur des objets personnalisés. Ils fournissent des contrôles d’édition, et récupèrent et mettent à jour des objets personnalisés dans le référentiel. Pour plus d’informations sur la configuration requise par les éditeurs et leurs fonctionnalités, voir Éditeurs pour les objets personnalisés des services PerformancePoint Services.
S’applique à : SharePoint Server 2010
Les éditeurs de rapport doivent également initialiser le point de terminaison du rapport, qui reçoit des valeurs de paramètres issues des fournisseurs de carte de performance et de filtre.
Les procédures et les exemples de cette rubrique sont basés sur la classe SampleReportViewEditor de l’exemple d’objets personnalisés. L’éditeur est une application Web légère permettant aux utilisateurs de modifier le nom et la description du rapport. Le code complet de la classe est fourni dans la section « Exemple » dans cette même rubrique.
Notes
Nous vous recommandons d’utiliser l’exemple d’éditeur comme modèle. L’exemple montre comment appeler des objets dans l’API PerformancePoint Services, fournit des objets d’assistance simplifiant les appels d’opérations de référentiel (création et mise à jour d’objets, par exemple) et présente les meilleures pratiques en matière de développement avec PerformancePoint Services.
Pour créer un éditeur de rapport, vous devez réaliser deux procédures de base :
Création et configuration de la classe de l’éditeur
Définition de la fonctionnalité d’édition
Pour créer un éditeur personnalisé, commencez par créer la classe de l’éditeur.
Pour créer et configurer la classe de l’éditeur
Installez PerformancePoint Services ou copiez sur votre ordinateur les DLL utilisées par votre extension (répertoriées dans l’étape 3). Pour plus d’informations, voir DLL PerformancePoint Services utilisées dans les scénarios de développement.
Dans Visual Studio, créez une bibliothèque de classes C#. Si vous avez déjà créé une bibliothèque de classes pour votre extension, ajoutez une nouvelle classe C#.
Ajouter les DLL PerformancePoint Services et SharePoint Server 2010 suivantes au projet en tant que références d’assembly :
Microsoft.PerformancePoint.Scorecards.Client.dll
Microsoft.PerformancePoint.Scorecards.ServerCommon.dll
Microsoft.PerformancePoint.Scorecards.Store.dll (utilisée par les classes d’assistance)
Microsoft.SharePoint.dll (utilisée par les classes d’assistance)
L’éditeur de l’exemple contient également des références d’assembly aux DLL System.Web.dll et System.Web.Services.dll. Selon le fonctionnement de votre extension, d’autres références de projet peuvent être requises.
Ajoutez les classes suivantes de l’exemple au projet. L’éditeur utilise ces classes d’assistance pour communiquer avec le référentiel PerformancePoint Services :
DataSourceConsumerHelper.cs
ExtensionRepositoryHelper.cs
ReportViewRepositoryHelper.cs
IDataSourceConsumer.cs
Notes
L’exemple de rapport obtient les données à l’aide d’un filtre et n’utilise donc pas les objets DataSourceConsumerHelper et IDataSourceConsumer. En revanche, si votre rapport contient des données issues d’une source de données PerformancePoint Services, vous pouvez utiliser les méthodes exposées par la classe DataSourceConsumerHelper pour récupérer les sources de données, comme expliqué dans Procédure : Créer des éditeurs pour les filtres des services PerformancePoint Services.
Dans votre classe d’éditeur, ajoutez des directives using pour les espaces de noms PerformancePoint Services suivants :
Microsoft.PerformancePoint.Scorecards
Microsoft.PerformancePoint.Scorecards.ServerCommon
Selon le fonctionnement de votre extension, d’autres directives using peuvent être requises.
Héritez de la classe de base prenant en charge votre implémentation d’éditeur. L’exemple d’éditeur de rapport étant une application Web, il hérite de la classe Page. D’autres implémentations peuvent être issues de classes de base, telles que les classes UserControl ou WebPart.
Une fois que vous avez créé et configuré la classe d’éditeur, vous devez définir le fonctionnement de votre éditeur.
Pour définir la fonctionnalité d’édition
Déclarez des variables pour les contrôles exposant les propriétés que vous souhaitez que les utilisateurs puissent afficher ou modifier. L’exemple d’éditeur de rapport commence par déclarer des variables pour les contrôles serveur Web définis dans le composant d’interface utilisateur, qui est une page ASPX. L’exemple d’éditeur définit également un contrôle bouton qui permet aux utilisateurs de soumettre des modifications. L’éditeur appelle ensuite la méthode CreateChildControls() pour rendre les contrôles disponibles sur la page.
Notes
L’éditeur définit la logique de programmation séparément de l’interface utilisateur. La méthode de création du composant d’interface utilisateur de l’éditeur dépasse le cadre de cette documentation.
Définissez la propriété AllowUnsafeUpdates sur true. Elle permet à l’éditeur de rapport d’écrire des données dans le référentiel sans utiliser des opérations POST de formulaire.
L’exemple d’éditeur de rapport réalise les étapes 2 à 6 dans la méthode Page_Load. La méthode Page_Load est également utilisée pour initialiser et valider des variables et des contrôles, renseigner les contrôles et enregistrer des informations d’état pour les objets de rapport et d’assistance personnalisés.
Récupérez les paramètres de la chaîne de requête et définissez-les comme valeurs pour les variables locales, comme dans l’exemple de code ci-dessous.
// The URL of the site collection that contains the PerformancePoint Services repository. string server = Request.QueryString[ClickOnceLaunchKeys.SiteCollectionUrl]; // The location of the report in the repository. string itemLocation = Request.QueryString[ClickOnceLaunchKeys.ItemLocation]; // The operation to perform: OpenItem or CreateItem. string action = Request.QueryString[ClickOnceLaunchKeys.LaunchOperation];Pour plus d’informations sur les paramètres de chaîne de requête, voir Éditeurs pour les objets personnalisés des services PerformancePoint Services.
Récupérez l’objet ReportViewRepositoryHelper, qui permet d’appeler le référentiel, comme le montre l’exemple de code suivant.
reportviewRepositoryHelper = new ReportViewRepositoryHelper();Définissez l’emplacement du rapport en fonction du paramètre de chaîne de requête, comme dans l’exemple de code suivant.
RepositoryLocation repositoryReportViewLocation = RepositoryLocation.CreateFromUriString(itemLocation);Récupérez l’opération à réaliser ( OpenItem ou CreateItem) auprès de la chaîne de requête, puis récupérez ou créez le rapport personnalisé, comme dans l’exemple de code suivant.
if (ClickOnceLaunchValues.OpenItem.Equals(action, StringComparison.OrdinalIgnoreCase)) { // Use the repository-helper object to retrieve the report. reportview = reportviewRepositoryHelper.Get(repositoryReportViewLocation); if (reportview == null) { displayError("Could not retrieve the report view for editing."); return; } } else if (ClickOnceLaunchValues.CreateItem.Equals(action, StringComparison.OrdinalIgnoreCase)) { reportview = new ReportView { RendererClassName = typeof(SampleReportRenderer).AssemblyQualifiedName, SubTypeId = "SampleReportView" }; } else { displayError("Invalid Action."); return; }Pour récupérer le rapport personnalisé, utilisez la méthode ReportViewRepositoryHelper.Get.
Pour créer le rapport personnalisé, utilisez le constructeur ReportView(), puis définissez les propriétés Name, RendererClassName et SubTypeId du rapport.
SubTypeId est l’identificateur unique du rapport et doit correspondre à l’attribut subType spécifié pour votre rapport personnalisé dans le fichier web.config de PerformancePoint Services. RendererClassName est le nom qualifié complet de la classe définissant le contrôle serveur Web de rendu. Si elle n’est pas définie dans l’éditeur, cette valeur prend par défaut la valeur de la classe de rendu spécifiée dans le fichier web.config.
Notes
Par défaut, les utilisateurs peuvent créer des objets personnalisés uniquement à partir de PerformancePoint Dashboard Designer. Pour permettre aux utilisateurs de créer un objet personnalisé en dehors de Dashboard Designer, vous devez ajouter un élément de menu qui envoie une demande CreateItem à votre éditeur à partir du type de contenu du référentiel. Pour plus d’informations, voir Éditeurs pour les objets personnalisés des services PerformancePoint Services.
Définissez le point de terminaison du rapport, qui permet au rapport de recevoir des données issues des filtres et des cartes de performance. L’exemple d’éditeur de rapport définit les propriétés requises pour le point de terminaison, comme dans l’exemple de code suivant.
if (0 == reportview.EndPoints.Count) { EndPoint endpoint = new EndPoint { Category = EndPointCategory.None, UniqueName = "SampleReportView_EndPoint", // The display name is shown to users in Dashboard Designer. // It represents the endpoint that can be connected // to a filter or scorecard. DisplayName = "Sample Report View EndPoint" }; reportview.EndPoints.Add(endpoint); }L’exemple d’éditeur définit le point de terminaison dans la méthode VerifyReportView. Il utilise également la méthode VerifyReportView pour vérifier que les propriétés requises sont définies et pour définir la propriété facultative CustomData, que vous pouvez utiliser pour stocker des informations destinées à votre rapport.
Mettez à jour le rapport pour prendre en compte les modifications définies par l’utilisateur. La méthode buttonOK_Click de l’exemple d’éditeur de rapport appelle la méthode ReportViewRepositoryHelper.Update pour mettre à jour les propriétés Name et Description dans le référentiel. La méthode buttonOK_Click est également utilisée pour valider le contenu des contrôles et récupérer les informations d’état du rapport personnalisé et de l’objet d’assistance.
Notes
Les utilisateurs peuvent modifier les propriétés Name, Description et Owner (Personne responsable) d’un objet personnalisé et supprimer des objets personnalisés directement à partir de Dashboard Designer et du référentiel PerformancePoint Services.
Étape suivante : après avoir créé un éditeur de rapport (notamment son interface utilisateur, le cas échéant) et un convertisseur de rapport, déployez l’extension comme décrit dans Procédure : enregistrer manuellement des extensions PerformancePoint Services. Pour obtenir des instructions sur la façon d’installer et de configurer l’exemple d’extension de filtre, voir la section « Installation des objets de rapport, de filtre et de source de données de l’exemple » dans Exemple de code : objets personnalisés de rapport, de filtre et de source de données tabulaires.
Exemple
L’exemple de code suivant crée, récupère et met à jour des rapports personnalisés dans le référentiel, et fournit la logique de programmation des contrôles définis dans une page ASPX.
Notes
Pour pouvoir compiler cet exemple de code, vous devez configurer votre environnement de développement en suivant les instructions fournies dans Pour créer et configurer la classe de l’éditeur.
using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.PerformancePoint.Scorecards;
using Microsoft.PerformancePoint.Scorecards.ServerCommon;
namespace Microsoft.PerformancePoint.SDK.Samples.SampleReport
{
// Represents the class that defines the sample report editor.
public class SampleReportViewEditor : Page
{
// Declare private variables for the ASP.NET controls defined in the user interface.
// The sample's user interface is an ASPX page that defines the controls in HTML.
private TextBox textboxName;
private TextBox textboxDescription;
private Label labelErrorMessage;
private Button buttonOK;
// Make the controls available to this class.
protected override void CreateChildControls()
{
base.CreateChildControls();
if (null == textboxName)
textboxName = FindControl("textboxName") as TextBox;
if (null == textboxDescription)
textboxDescription = FindControl("textboxDescription") as TextBox;
if (null == labelErrorMessage)
labelErrorMessage = FindControl("labelErrorMessage") as Label;
if (null == buttonOK)
buttonOK = FindControl("buttonOK") as Button;
}
// Handles the Load event of the Page control.
// Methods that use a control variable should call the Control.EnsureChildControls
// method before accessing the variable for the first time.
protected void Page_Load(object sender, EventArgs e)
{
// Required to enable custom report and filter editors to
// write data to the repository.
ServerUtils.AllowUnsafeUpdates = true;
// Initialize controls the first time the page loads only.
if (!IsPostBack)
{
EnsureChildControls();
ReportViewRepositoryHelper reportviewRepositoryHelper = null;
try
{
// Get information from the query string parameters.
string server = Request.QueryString[ClickOnceLaunchKeys.SiteCollectionUrl];
string itemLocation = Request.QueryString[ClickOnceLaunchKeys.ItemLocation];
string action = Request.QueryString[ClickOnceLaunchKeys.LaunchOperation];
// Validate the query string parameters.
if (string.IsNullOrEmpty(server) ||
string.IsNullOrEmpty(itemLocation) ||
string.IsNullOrEmpty(action))
{
displayError("Invalid URL.");
return;
}
// Retrieve the repository-helper object.
reportviewRepositoryHelper =
new ReportViewRepositoryHelper();
// Set the report location by using the location from the query string.
RepositoryLocation repositoryReportViewLocation = RepositoryLocation.CreateFromUriString(itemLocation);
ReportView reportview;
// Retrieve or create the report object, depending on the operation
// passed in the query string (OpenItem or CreateItem).
if (ClickOnceLaunchValues.OpenItem.Equals(action, StringComparison.OrdinalIgnoreCase))
{
// Retrieve the report object by using the repository-helper object.
reportview = reportviewRepositoryHelper.Get(repositoryReportViewLocation);
if (reportview == null)
{
displayError("Could not retrieve the report view for editing.");
return;
}
}
else if (ClickOnceLaunchValues.CreateItem.Equals(action, StringComparison.OrdinalIgnoreCase))
{
// Create a report view.
// CreateItem requests can be sent from a SharePoint list, but
// you must create a custom menu item to send the request.
// Dashboard Designer can send edit requests only.
reportview = new ReportView
{
RendererClassName = typeof(SampleReportRenderer).AssemblyQualifiedName,
SubTypeId = "SampleReportView"
};
}
else
{
displayError("Invalid Action.");
return;
}
VerifyReportView(reportview);
// Save the original report and helper objects across page postbacks.
ViewState["action"] = action;
ViewState["reportview"] = reportview;
ViewState["reportviewrepositoryhelper"] = reportviewRepositoryHelper;
ViewState["itemlocation"] = itemLocation;
// Populate the child controls.
textboxName.Text = reportview.Name.ToString();
textboxDescription.Text = reportview.Description.ToString();
}
catch (Exception ex)
{
displayError("An error has occurred. Please contact your administrator for more information.");
if (reportviewRepositoryHelper != null)
{
// Add the exception detail to the server event log.
reportviewRepositoryHelper.HandleException(ex);
}
}
}
}
// Handles the Click event of the buttonOK control.
protected void buttonOK_Click(object sender, EventArgs e)
{
EnsureChildControls();
// Verify that the textboxName control contains a value.
if (string.IsNullOrEmpty(textboxName.Text))
{
labelErrorMessage.Text = "A report view name is required.";
return;
}
// Clear any pre-existing error message.
labelErrorMessage.Text = string.Empty;
// Retrieve the report and helper objects from view state.
string action = (string)ViewState["action"];
string itemLocation = (string) ViewState["itemlocation"];
ReportView reportview = (ReportView)ViewState["reportview"];
ReportViewRepositoryHelper reportviewRepositoryHelper = (ReportViewRepositoryHelper)ViewState["reportviewrepositoryhelper"];
// Update the report object with form changes.
reportview.Name.Text = textboxName.Text;
reportview.Description.Text = textboxDescription.Text;
// Save the report object to the PerformancePoint Services repository.
try
{
reportview.Validate();
if (ClickOnceLaunchValues.CreateItem.Equals(action, StringComparison.OrdinalIgnoreCase))
{
reportview.CreatedDate = DateTime.Now;
ReportView newReportView = reportviewRepositoryHelper.Create(
string.IsNullOrEmpty(reportview.Location.ItemUrl) ? itemLocation : reportview.Location.ItemUrl,
reportview);
ViewState["reportview"] = newReportView;
ViewState["action"] = ClickOnceLaunchValues.OpenItem;
}
else
{
reportviewRepositoryHelper.Update(reportview);
}
}
catch (Exception ex)
{
displayError("An error has occurred. Please contact your administrator for more information.");
if (reportviewRepositoryHelper != null)
{
// Add the exception detail to the server event log.
reportviewRepositoryHelper.HandleException(ex);
}
}
}
// Displays the error string in the labelErrorMessage label.
void displayError(string msg)
{
EnsureChildControls();
labelErrorMessage.Text = msg;
// Disable the OK button because the page is in an error state.
buttonOK.Enabled = false;
return;
}
// Verifies that the properties for the report object are set.
static void VerifyReportView(ReportView reportview)
{
// Verify that all required properties are set.
if (string.IsNullOrEmpty(reportview.SubTypeId))
{
// This value must match the subType attribute specified
// in the web.config file.
reportview.SubTypeId = "SampleReportView";
}
if (string.IsNullOrEmpty(reportview.RendererClassName))
{
reportview.RendererClassName = typeof (SampleReportRenderer).AssemblyQualifiedName;
}
// Reports are consumers and do not use provider endpoints.
reportview.BeginPoints.Clear();
// If there are no consumer endpoints, create one so we can connect a filter or a scorecard to the report.
if (0 == reportview.EndPoints.Count)
{
EndPoint endpoint = new EndPoint
{
Category = EndPointCategory.None,
UniqueName = "SampleReportView_EndPoint",
// The display name is shown to users in Dashboard
// Designer to represent the endpoint that can be
// connected to a filter or scorecard.
DisplayName = "Sample Report View EndPoint"
};
reportview.EndPoints.Add(endpoint);
}
// Set optional properties for reports.
reportview.CustomData = "You can use this property to store custom information for this filter as a string or a serialized object.";
}
}
}
Compilation du code
Pour pouvoir compiler cet exemple de code, vous devez configurer votre environnement de développement en suivant les instructions fournies dans Pour créer et configurer la classe de l’éditeur.
Sécurité
Vous devez signer votre DLL en utilisant un nom fort. En outre, assurez-vous que tous les assemblys référencés par votre DLL portent des noms forts. Pour plus d’informations sur la signature d’un assembly en utilisant un nom fort et la création d’une paire de clés privée/publique, voir How to: Create a Public/Private Key Pair.
Voir aussi
Tâches
Procédure : créer des convertisseurs pour les rapports des services PerformancePoint Services
Concepts
Éditeurs pour les objets personnalisés des services PerformancePoint Services
Autres ressources
Créer des objets personnalisés pour les services PerformancePoint Services
Exemples de code pour les pour les services PerformancePoint Services dans SharePoint Server 2010