Erstellen einer Entwurfszeitkomponente für ein benutzerdefiniertes BerichtselementCreating a Custom Report Item Design-Time Component

Die Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement ist eine Steuerung, die in der Berichts-Designer-Umgebung von Visual Studio verwendet werden kann.A custom report item design-time component is a control that can be used in the Visual Studio Report Designer environment. Diese Komponente bietet eine aktivierte Entwurfsoberfläche, die Drag und Drop-Vorgänge, Integration in den Eigenschaftenbrowser von Visual StudioVisual Studio und die Möglichkeit zum Bereitstellen von Editoren für benutzerdefinierte Eigenschaften zulassen.The custom report item design-time component provides an activated design surface that can accept drag-and-drop operations, integration with the Visual StudioVisual Studio property browser, and the ability to provide custom property editors.

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.With a custom report item design-time component, the user can position a custom report item on a report in the design environment, set custom data properties on the custom report item, and then save the custom report item as part of the report project.

Die mit der Entwurfszeitkomponente der Entwicklungsumgebung festgelegten Eigenschaften werden von der Host-Entwurfsumgebung serialisiert und deserialisiert und dann als Elemente in der RDL-Datei (Report Definition Language, Berichtsdefinitionssprache) gespeichert.The properties that are set using the design-time component in the development environment are serialized and deserialized by the host design environment and then stored as elements in the Report Definition Language (RDL) file. Wenn der Bericht vom Berichtsprozessor ausgeführt wird, werden die mit der Entwurfszeitkomponente festgelegten Eigenschaften vom Berichtsprozessor an eine Laufzeitkomponente für ein benutzerdefiniertes Berichtselement übergeben, die das benutzerdefinierte Berichtselement rendert und wieder an den Berichtsprozessor zurückgibt.When the report is executed by the report processor, the properties that are set using the design-time component are passed by the report processor to a custom report item run-time component, which renders the custom report item and passes it back to the report processor.

Hinweis

Die Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement wird als MicrosoftMicrosoft.NET Framework.NET Framework-Komponente implementiert.The custom report item design-time component is implemented as a MicrosoftMicrosoft.NET Framework.NET Framework component. In diesem Dokument werden Implementierungsdetails beschrieben, die für die Entwurfszeitkomponente eines benutzerdefinierten Berichtselements spezifisch sind.This document will describe implementation details specific to the custom report item design-time component. Weitere Informationen zum Entwickeln von Komponenten mit .NET Framework.NET Framework finden Sie in der MSDN Library unter Komponenten in Visual Studio.For more information about developing components using the .NET Framework.NET Framework, see Components in Visual Studio in the MSDN library.

Ein Beispiel für ein vollständig implementiertes benutzerdefiniertes Berichtselement finden Sie unter SQL Server Reporting Services-Produktbeispiele.For a sample of a fully implemented custom report item, see SQL Server Reporting Services Product Samples.

Implementieren einer EntwurfszeitkomponenteImplementing a Design-Time Component

Die Hauptklasse einer Entwurfszeitkomponente für ein benutzerdefiniertes Berichtselement wird von der Microsoft.ReportDesigner.CustomReportItemDesigner-Klasse geerbt.The main class of a custom report item design-time component is inherited from the Microsoft.ReportDesigner.CustomReportItemDesigner class. Zusätzlich zu den Standardattributen für eine .NET Framework.NET Framework-Steuerung sollte die Komponentenklasse ein CustomReportItem-Attribut definieren.In addition to the standard attributes used for a .NET Framework.NET Framework control, your component class should define a CustomReportItem attribute. Dieses Attribut muss dem in der Datei reportserver.config festgelegten Namen des benutzerdefinierten Berichtselements entsprechen.This attribute must correspond to the name of the custom report item as it is defined in the reportserver.config file. Eine Liste der .NET Framework.NET Framework-Attribute finden Sie unter "Attribute" in der .NET Framework.NET Framework-SDK-Dokumentation.For a list of .NET Framework.NET Framework attributes, see Attributes in the .NET Framework.NET Framework SDK documentation.

Im folgenden Codebeispiel wird gezeigt, wie Attribute auf eine Entwurfszeitsteuerung für ein benutzerdefiniertes Berichtselement angewendet werden:The following code example shows attributes being applied to a custom report item design-time control:

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

Initialisieren der KomponenteInitializing the Component

Sie übergeben benutzerspezifische Eigenschaften für ein benutzerdefiniertes Berichtselement mit einer CustomData-Klasse.You pass user-specified properties for a custom report item using a CustomData class. 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.Your implementation of the CustomReportItemDesigner class should override the InitializeNewComponent method to create a new instance of your component's CustomData class and set it to default values.

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:The following code example shows an example of a custom report item design-time component class overriding the CustomReportItemDesigner.InitializeNewComponent method to initialize the component's CustomData class:

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 KomponenteneigenschaftenModifying Component Properties

Sie können CustomData-Eigenschaften auf verschiedene Arten in der Entwurfsumgebung ändern.You can modify CustomData properties in the design environment in several ways. Mit dem Visual StudioVisual Studio-Eigenschaftenbrowser können Sie jede Eigenschaft ändern, die von der Entwurfszeitkomponente verfügbar gemacht wurde und die mit dem BrowsableAttribute-Attribut gekennzeichnet sind.You can modify any properties that are exposed by the design-time component that are marked with the BrowsableAttribute attribute by using the Visual StudioVisual Studio property browser. 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.In addition, you can modify properties by dragging items onto the custom report item's design surface, or by right-clicking the control in the design environment and selecting Properties on the shortcut menu to display a custom properties window.

Das folgende Codebeispiel zeigt eine Microsoft.ReportDesigner.CustomReportItemDesigner.CustomData-Eigenschaft, auf die das BrowsableAttribute-Attribut angewendet wurde:The following code example shows a Microsoft.ReportDesigner.CustomReportItemDesigner.CustomData property that has the BrowsableAttribute attribute applied:

[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.You can provide your design-time component with a custom properties editor dialog box. 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.The custom property editor implementation should inherit from the ComponentEditor class, and it should create an instance of a dialog box that can be used for property editing.

Im folgenden Beispiel wird die Implementierung einer Klasse, die von ComponentEditor erbt, und ein Dialogfeld eines Editors für benutzerdefinierte Eigenschaften dargestellt:The following example shows an implementation of a class that inherits from ComponentEditor and displays a custom property editor dialog box:

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.Your custom property editor dialog box can invoke the Report Designer Expression Editor. Im folgenden Beispiel wird der Ausdrucks-Editor aufgerufen, wenn der Benutzer das erste Element im Kombinationsfeld auswählt:In the following example, the Expression Editor is invoked when the user selects the first element in the combo box:

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 DesignerverbenUsing Designer Verbs

Ein Designerverb ist ein mit einem Ereignishandler verknüpfter Menübefehl.A designer verb is a menu command linked to an event handler. Sie können Designerverben hinzufügen, die im Kontextmenü einer Komponente angezeigt werden, wenn die Laufzeitsteuerung für ein benutzerdefiniertes Berichtselement in der Entwurfsumgebung verwendet wird.You can add designer verbs that will appear in a component's shortcut menu when your custom report item run-time control is being used in the design environment. Mit der Verbs-Eigenschaft können Sie die Liste der verfügbaren Designerverben von der Laufzeitkomponente zurückgeben.You can return the list of available designer verbs from your run-time component by using the Verbs property.

Im folgenden Codebeispiel wird gezeigt, wie ein Designerverb und ein Ereignishandler zu DesignerVerbCollection hinzugefügt wird, sowie der Ereignishandlercode dargestellt:The following code example shows a designer verb and an event handler being added to the DesignerVerbCollection, as well as the event handler code:

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 RandsteuerelementenUsing Adornments

Benutzerdefinierte Berichtselementklassen können ebenfalls eine Microsoft.ReportDesigner.Design.Adornment-Klasse implementieren.Custom report item classes can also implement a Microsoft.ReportDesigner.Design.Adornment class. Ein Randsteuerelement ermöglicht es der Steuerung für ein benutzerdefiniertes Berichtselement, Bereiche außerhalb des Hauptrechtecks der Entwurfsoberfläche bereitzustellen.An adornment allows the custom report item control to provide areas outside the main rectangle of the design surface. Diese Bereiche behandeln Benutzeroberflächenereignisse wie Mausklicks und Drag und Drop-Vorgänge.These areas can handle user interface events, such as mouse clicks and drag-and-drop operations. Die im Reporting ServicesReporting Services Microsoft.ReportDesigner-Namespace definierte Adornment-Klasse ist eine Pass-Through-Implementierung der Adorner-Klasse, die in Windows Forms enthalten ist.The Adornment class that is defined in the Reporting ServicesReporting Services Microsoft.ReportDesigner namespace is a pass-through implementation of the Adorner class found in Windows Forms. Eine vollständige Dokumentation zur Adorner-Klasse finden Sie unter Übersicht über den Behavior-Dienst in der MSDN Library.For complete documentation on the Adorner class, see Behavior Service Overview in the MSDN library. Beispielcode, in dem eine Microsoft.ReportDesigner.Design.Adornment-Klasse implementiert wird, finden Sie unter SQL Server Reporting Services-Produktbeispiele.For sample code that implements a Microsoft.ReportDesigner.Design.Adornment class, see SQL Server Reporting Services Product Samples.

Weitere Informationen zum Programmieren und Verwenden von Windows Forms in Visual StudioVisual Studio finden Sie in diesen Themen in der MSDN Library:For more information about programming and using Windows Forms in Visual StudioVisual Studio, see these topics in the MSDN Library:

  • Entwurfszeitattribute für KomponentenDesign-Time Attributes for Components

  • Komponenten in Visual StudioVisual StudioComponents in Visual StudioVisual Studio

  • Exemplarische Vorgehensweise: Erstellen eines Windows Forms-Steuerelements, das Visual Studio-Entwurfszeitfunktionen nutztWalkthrough: Creating a Windows Forms Control that Takes Advantage of Visual Studio Design-Time Features

Weitere InformationenSee Also

Custom Report Item Architecture (Architektur des benutzerdefinierten Berichtselements) Custom Report Item Architecture
Erstellen einer Laufzeitkomponente für ein benutzerdefiniertes Berichtselement Creating a Custom Report Item Run-Time Component
Custom Report Item Class Libraries (Klassenbibliotheken für ein benutzerdefiniertes Berichtselement) Custom Report Item Class Libraries
Vorgehensweise: Bereitstellen eines benutzerdefinierten BerichtselementsHow to: Deploy a Custom Report Item