Erstellen einer benutzerdefinierten Entwurfszeitkomponente für Berichtselemente

  • Artikel

Die Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement ist eine Steuerung, die in der Berichts-Designer-Umgebung von Visual Studio verwendet werden kann. Diese Komponente bietet eine aktivierte Entwurfsoberfläche, die Drag & Drop-Vorgänge, die Integration in den Eigenschaftenbrowser von Visual Studio und die Möglichkeit zum Bereitstellen von Editoren für benutzerdefinierte Eigenschaften akzeptiert.

Mit der Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement können Benutzer ein benutzerdefiniertes Berichtselement auf einem Bericht in der Entwurfsumgebung positionieren, benutzerdefinierte Dateneigenschaften auf dem benutzerdefinierten Berichtselement festlegen und das benutzerdefinierte Berichtselement anschließend als Teil des Berichtsprojekts speichern.

Die Eigenschaften, die mithilfe der Entwurfszeitkomponente in der Entwicklungsumgebung festgelegt werden, werden von der Hostentwurfsumgebung serialisiert und deserialisiert. Die Eigenschaften werden dann als Elemente in der RDL-Datei (Report Definition Language) gespeichert. Wenn der Berichtsprozessor den Bericht ausführt, werden die Eigenschaften, die mithilfe der Entwurfszeitkomponente festgelegt werden, vom Berichtsprozessor an eine benutzerdefinierte Laufzeitkomponente des Berichtselements übergeben, die das benutzerdefinierte Berichtselement rendert und an den Berichtsprozessor zurückgibt.

Hinweis

Die Entwurfszeitkomponente für benutzerdefinierte Berichtselemente ist als Microsoft.NET Framework-Komponente implementiert. In diesem Dokument werden Implementierungsdetails beschrieben, die für die Entwurfszeitkomponente eines benutzerdefinierten Berichtselements spezifisch sind.

Ein Beispiel für ein vollständig implementiertes benutzerdefiniertes Berichtselement finden Sie unter SQL Server Reporting Services-Produktbeispiele.

Implementieren einer Entwurfszeitkomponente

Die Hauptklasse einer Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement wird von der Microsoft.ReportDesigner.CustomReportItemDesigner-Klasse geerbt. Zusätzlich zu den Standardattributen für eine Microsoft.NET Framework-Steuerung sollte Ihre Komponentenklasse ein CustomReportItem-Attribut definieren. Dieses Attribut muss dem in der Datei reportserver.config festgelegten Namen des benutzerdefinierten Berichtselements entsprechen. Eine Liste mit .NET Framework-Attributen finden Sie in der .NET Framework SDK-Dokumentation.

Im folgenden Codebeispiel wird gezeigt, wie Attribute auf eine Entwurfszeitsteuerung für ein benutzerdefiniertes Berichtselement angewendet werden:

namespace PolygonsCRI  
{  
    [LocalizedName("Polygons")]  
    [Editor(typeof(CustomEditor), typeof(ComponentEditor))]  
        [ToolboxBitmap(typeof(PolygonsDesigner),"Polygons.ico")]  
        [CustomReportItem("Polygons")]  
  
    public class PolygonsDesigner : CustomReportItemDesigner  
    {  
...

Initialisieren der Komponente

Sie übergeben benutzerspezifische Eigenschaften für ein benutzerdefiniertes Berichtselement mit einer CustomData-Klasse. Die Implementierung der CustomReportItemDesigner-Klasse sollte die InitializeNewComponent-Methode überschreiben, um eine neue Instanz der CustomData-Klasse Ihrer Komponente zu erstellen und sie auf die Standardwerte festzulegen.

Im folgenden Codebeispiel wird ein Beispiel dafür gezeigt, wie die Klasse einer Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement die CustomReportItemDesigner.InitializeNewComponent-Methode überschreibt, um die CustomData-Klasse der Komponente zu initialisieren:

public override void InitializeNewComponent()  
        {  
            CustomData = new CustomData();  
            CustomData.DataRowHierarchy = new DataHierarchy();  
  
            // Shape grouping  
            CustomData.DataRowHierarchy.DataMembers.Add(new DataMember());  
            CustomData.DataRowHierarchy.DataMembers[0].Group = new Group();  
            CustomData.DataRowHierarchy.DataMembers[0].Group.Name = Name + "_Shape";  
            CustomData.DataRowHierarchy.DataMembers[0].Group.GroupExpressions.Add(new ReportExpression());  
  
            // Point grouping  
            CustomData.DataRowHierarchy.DataMembers[0].DataMembers.Add(new DataMember());  
            CustomData.DataRowHierarchy.DataMembers[0].DataMembers[0].Group = new Group();  
            CustomData.DataRowHierarchy.DataMembers[0].DataMembers[0].Group.Name = Name + "_Point";  
            CustomData.DataRowHierarchy.DataMembers[0].DataMembers[0].Group.GroupExpressions.Add(new ReportExpression());  
  
            // Static column  
            CustomData.DataColumnHierarchy = new DataHierarchy();  
            CustomData.DataColumnHierarchy.DataMembers.Add(new DataMember());  
  
            // Points  
            IList<IList<DataValue>> dataValues = new List<IList<DataValue>>();  
            CustomData.DataRows.Add(dataValues);  
            CustomData.DataRows[0].Add(new List<DataValue>());  
            CustomData.DataRows[0][0].Add(NewDataValue("X", ""));  
            CustomData.DataRows[0][0].Add(NewDataValue("Y", ""));  
        }

Ändern von Komponenteneigenschaften

Sie können CustomData-Eigenschaften auf verschiedene Arten in der Entwurfsumgebung ändern. Mit dem Eigenschaftenbrowser von Visual Studio können Sie alle Eigenschaften ändern, die von der Entwurfszeitkomponente verfügbar gemacht wurden und mit dem Attribut BrowsableAttribute gekennzeichnet sind. Außerdem können Sie Eigenschaften ändern, indem Sie Elemente auf die Entwurfsoberfläche des benutzerdefinierten Berichtselements ziehen oder mit der rechten Maustaste auf die Steuerung in der Entwurfsumgebung klicken und im Kontextmenü Eigenschaften auswählen, um ein benutzerdefiniertes Eigenschaftenfenster aufzurufen.

Das folgende Codebeispiel zeigt eine Microsoft.ReportDesigner.CustomReportItemDesigner.CustomData-Eigenschaft, auf die das BrowsableAttribute-Attribut angewendet wurde:

[Browsable(true), Category("Data")]  
public string DataSetName  
{  
      get  
      {  
         return CustomData.DataSetName;  
      }  
      set  
      {  
         CustomData.DataSetName = value;  
      }  
   }

Sie können für Ihre Entwurfszeitkomponente ein Dialogfeld für benutzerdefinierte Eigenschaften bereitstellen. Die Implementierung des Editors für benutzerdefinierte Eigenschaften sollte von der ComponentEditor-Klasse erben und eine Instanz eines Dialogfelds erstellen, die für die Bearbeitung der Eigenschaften verwendet werden kann.

Im folgenden Beispiel wird die Implementierung einer Klasse, die von ComponentEditor erbt, und ein Dialogfeld eines Editors für benutzerdefinierte Eigenschaften dargestellt:

internal sealed class CustomEditor : ComponentEditor  
{  
   public override bool EditComponent(  
      ITypeDescriptorContext context, object component)  
    {  
     PolygonsDesigner designer = (PolygonsDesigner)component;  
     PolygonProperties dialog = new PolygonProperties();  
     dialog.m_designerComponent = designer;  
     DialogResult result = dialog.ShowDialog();  
     if (result == DialogResult.OK)  
     {  
        designer.Invalidate();  
        designer.ChangeService().OnComponentChanged(designer, null, null, null);  
        return true;  
     }  
     else  
        return false;  
    }  
}

Das Dialogfeld des Editors für benutzerdefinierte Eigenschaften kann den Ausdrucks-Editor des Berichts-Designers aufrufen. Im folgenden Beispiel wird der Ausdrucks-Editor aufgerufen, wenn der Benutzer das erste Element im Kombinationsfeld auswählt:

private void EditableCombo_SelectedIndexChanged(object sender,   
    EventArgs e)  
{  
   ComboBox combo = (ComboBox)sender;  
   if (combo.SelectedIndex == 0 && m_launchEditor)  
   {  
      m_launchEditor = false;  
      ExpressionEditor editor = new ExpressionEditor();  
      string newValue;  
      newValue = (string)editor.EditValue(null, m_designerComponent.Site, m_oldComboValue);  
      combo.Items[0] = newValue;  
   }  
}

Verwenden von Designerverben

Ein Designerverb ist ein mit einem Ereignishandler verknüpfter Menübefehl. Sie können Designerverben hinzufügen, die im Kontextmenü einer Komponente angezeigt werden, wenn das Laufzeitsteuerelement des benutzerdefinierten Berichtselements in der Entwurfsumgebung verwendet wird. Mit der Verbs-Eigenschaft können Sie die Liste der verfügbaren Designerverben von der Laufzeitkomponente zurückgeben.

Das folgende Codebeispiel zeigt ein Designerverb und einen Ereignishandler, der der DesignerVerbCollection. Das Beispiel zeigt auch den Ereignishandlercode:

public override DesignerVerbCollection Verbs  
{  
    get  
    {  
        if (m_verbs == null)  
        {  
            m_verbs = new DesignerVerbCollection();  
            m_verbs.Add(new DesignerVerb("Proportional Scaling", new EventHandler(OnProportionalScaling)));  
         m_verbs[0].Checked = (GetCustomProperty("poly:Proportional") == bool.TrueString);  
        }  
  
        return m_verbs;  
    }  
}  
  
private void OnProportionalScaling(object sender, EventArgs e)  
{  
   bool proportional = !  
        (GetCustomProperty("poly:Proportional") == bool.TrueString);  
   m_verbs[0].Checked = proportional;  
   SetCustomProperty("poly:Proportional", proportional.ToString());  
   ChangeService().OnComponentChanged(this, null, null, null);  
   Invalidate();  
}

Verwenden von Schmücken

Benutzerdefinierte Berichtselementklassen können ebenfalls eine Microsoft.ReportDesigner.Design.Adornment-Klasse implementieren. Ein Randsteuerelement ermöglicht es der Steuerung für ein benutzerdefiniertes Berichtselement, Bereiche außerhalb des Hauptrechtecks der Entwurfsoberfläche bereitzustellen. Diese Bereiche behandeln Benutzeroberflächenereignisse wie Mausklicks und Drag und Drop-Vorgänge. Die im Microsoft.ReportDesigner-Namespace von Reporting Services definierte Adornment-Klasse ist eine Passthrough-Implementierung der Adorner-Klasse, die in Windows Forms enthalten ist. Eine vollständige Dokumentation zur Adorner-Klasse finden Sie unter Übersicht über den Behavior-Dienst in der MSDN Library. Beispielcode, in dem eine Microsoft.ReportDesigner.Design.Adornment-Klasse implementiert wird, finden Sie unter SQL Server Reporting Services-Produktbeispiele.

Weitere Informationen zum Programmieren und Verwenden von Windows Forms in Visual Studio finden Sie in den folgenden Artikeln in der MSDN Library:

  • Entwurfszeitattribute für Komponenten

  • Komponenten in Visual Studio

  • Exemplarische Vorgehensweise: Erstellen eines Windows Forms-Steuerelements, das Visual Studio-Entwurfszeitfunktionen nutzt

Zugehöriger Inhalt

Architektur eines benutzerdefinierten Berichtselements
Erstellen einer benutzerdefinierten Laufzeitkomponente für Berichtselemente
Benutzerdefinierte Berichtselementklassenbibliotheken
Vorgehensweise: Bereitstellen eines benutzerdefinierten Berichtselements