This documentation is archived and is not being maintained.

DesignerTransaction Class

Provides a way to group a series of design-time actions to improve performance and enable most types of changes to be undone.

System::Object
  System.ComponentModel.Design::DesignerTransaction

Namespace:  System.ComponentModel.Design
Assembly:  System (in System.dll)

[HostProtectionAttribute(SecurityAction::LinkDemand, SharedState = true)]
[PermissionSetAttribute(SecurityAction::InheritanceDemand, Name = L"FullTrust")]
public ref class DesignerTransaction abstract : IDisposable

The DesignerTransaction type exposes the following members.

  NameDescription
Protected methodDesignerTransaction()Initializes a new instance of the DesignerTransaction class with no description.
Protected methodDesignerTransaction(String)Initializes a new instance of the DesignerTransaction class using the specified transaction description.
Top

  NameDescription
Public propertyCanceledGets a value indicating whether the transaction was canceled.
Public propertyCommittedGets a value indicating whether the transaction was committed.
Public propertyDescriptionGets a description for the transaction.
Top

  NameDescription
Public methodCancelCancels the transaction and attempts to roll back the changes made by the events of the transaction.
Public methodCommitCommits this transaction.
Protected methodDisposeReleases the unmanaged resources used by the DesignerTransaction and optionally releases the managed resources.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeReleases the resources associated with this object. This override commits this transaction if it was not already committed. (Overrides Object::Finalize().)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnCancelRaises the Cancel event.
Protected methodOnCommitPerforms the actual work of committing a transaction.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Explicit interface implemetationPrivate methodIDisposable::DisposeReleases all resources used by the DesignerTransaction.
Top

Transactions can track actions that can be undone later. Changes made during a transaction can be reversed by canceling a transaction, which automatically attempts to reverse each change by setting each changed property to its pre-change value. Transactions can also improve performance during a series of operations by deferring updates to the display until the completion of the transaction.

When a transaction is in progress, some components defer their processing until the transaction has completed by listening to the TransactionOpening and TransactionClosed events. The Properties window, for example, does not update its display after a transaction has opened until the transaction has closed.

To use transactions for reversible or multiple operations, have your designer create a DesignerTransaction for each operation or series of operations which should be reversible. Be careful not to perform actions outside the transactions that might prevent a sequence of undo events from completing successfully.

You can obtain a new DesignerTransaction by calling the CreateTransaction method of an IDesignerHost. Be sure to obtain each DesignerTransaction from the active IDesignerHost in order to correctly integrate with the designer transaction processing mechanism, rather than creating a new DesignerTransaction directly.

To perform an action within a transaction, you must first create a transaction. Then you must call the OnComponentChanging method before each change or set of changes occurs, and the OnComponentChanged method after each change or set of changes occur. Finally, complete and close the transaction by calling the Commit method.

NoteNote

When making changes to property values, use the SetValue method of a PropertyDescriptor, which calls the component change methods of the IComponentChangeService and creates a DesignerTransaction representing the change automatically.

To perform a transaction, complete the following steps:

  1. Call CreateTransaction to obtain a DesignerTransaction that can be used to control the transaction.

  2. Within a try block, for each action that you want to track with a DesignerTransaction, call the OnComponentChanging method, make the change or changes, then call the OnComponentChanged method to signal that the change or changes have been made.

  3. To complete the transaction, call Commit from within a finally block.

In C#, you can use the using statement rather than a try/finally block, such as in the following example.

 using (host.CreateTransaction() {
 // Insert your code here.
 }

To cancel and attempt to roll back a transaction before it has been committed, call the Cancel method. When the Cancel method is invoked, the actions tracked by the DesignerTransaction are reversed to attempt to roll back the changes. To undo actions that occurred as part of earlier transactions, you must use the undo command provided by the development environment.

NoteNote

The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: SharedState. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes.

The following code example program demonstrates how to create a DesignerTransaction from a designer. To run this sample, compile the source code into a class library. You must add a reference to the System.Design assembly. In a new project, add a reference to the compiled DLL and add the component in the library to the Toolbox.

There is extensive support for this feature in Visual Studio.

For more information, see Walkthrough: Automatically Populating the Toolbox with Custom Components and Walkthrough: Automatically Populating the Toolbox with Custom Components and Walkthrough: Automatically Populating the Toolbox with Custom Components and Walkthrough: Automatically Populating the Toolbox with Custom Components.

The designer can optionally display notifications about designer transaction events. If you add an instance of the DTComponent to a form while in design mode, a message box appears asking whether you would like to receive designer transaction event notifications. You may toggle these notifications using the shortcut menu that appears when you right-click an instance of the DTComponent. Transactions are created when you change values using the Properties window. You can also have the designer perform a transaction by clicking Perform Example Transaction on the shortcut menu for the component.


#using <system.dll>
#using <system.design.dll>
#using <system.windows.forms.dll>

using namespace System;
using namespace System::ComponentModel;
using namespace System::ComponentModel::Design;
using namespace System::Windows::Forms;
using namespace System::Windows::Forms::Design;

/*
This sample demonstrates how to perform a series of actions in a designer
transaction, how to change values of properties of a component from a
designer, and how to complete transactions without being interrupted
by other activities.

To run this sample, add this code to a class library project and compile.
Create a new Windows Forms project or load a form in the designer. Add a
reference to the class library that was compiled in the first step.
Right-click the Toolbox in design mode and click Customize Toolbox.
Browse to the class library that was compiled in the first step and
select OK until the DTComponent item appears in the Toolbox.  Add an
instance of this component to the form.

When the component is created and added to the component tray for your
design project, the Initialize method of the designer is called.
This method displays a message box informing you that designer transaction
event handlers will be registered unless you click Cancel. When you set
properties in the properties window, each change will be encapsulated in
a designer transaction, allowing the change to be undone later.

When you right-click the component, the shortcut menu for the component
is displayed. The designer constructs this menu according to whether
designer transaction notifications are enabled, and offers the option
of enabling or disabling the notifications, depending on the current
mode. The shortcut menu also presents a Perform Example Transaction
item, which will set the values of the component's StringProperty and
CountProperty properties. You can undo the last designer transaction using
the Undo command provided by the Visual Studio development environment.
*/

private ref class DTDesigner: public ComponentDesigner
{
private:
   bool notification_mode;
   int count;
   void LinkDTNotifications( Object^ /*sender*/, EventArgs^ /*e*/ )
   {
      if (  !notification_mode )
      {
         IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
         if ( host != nullptr )
         {
            notification_mode = true;
            host->TransactionOpened += gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
            host->TransactionClosed += gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
         }
      }
   }

   void UnlinkDTNotifications( Object^ /*sender*/, EventArgs^ /*e*/ )
   {
      if ( notification_mode )
      {
         IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
         if ( host != nullptr )
         {
            notification_mode = false;
            host->TransactionOpened -= gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
            host->TransactionClosed -= gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
         }
      }
   }

   void OnDesignerTransactionOpened( Object^ /*sender*/, EventArgs^ /*e*/ )
   {
      MessageBox::Show( "A Designer Transaction was started. (TransactionOpened)" );
   }

   void OnDesignerTransactionClosed( Object^ /*sender*/, DesignerTransactionCloseEventArgs^ /*e*/ )
   {
      MessageBox::Show( "A Designer Transaction was completed. (TransactionClosed)" );
   }

   void DoTransaction( Object^ /*sender*/, EventArgs^ /*e*/ )
   {
      IDesignerHost^ host = static_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
      DesignerTransaction^ t = host->CreateTransaction( "Change Text and Size" );

      /* The code within the using statement is considered to be a single transaction.
              When the user selects Undo, the system will undo everything executed in this code block.
              */
      if ( notification_mode )
            MessageBox::Show( "Entering a Designer-Initiated Designer Transaction" );

      // The .NET Framework automatically associates the TypeDescriptor with the correct component
      PropertyDescriptor^ someText = TypeDescriptor::GetProperties( Component )[ "StringProperty" ];
      someText->SetValue( Component, "This text was set by the designer for this component." );
      PropertyDescriptor^ anInteger = TypeDescriptor::GetProperties( Component )[ "CountProperty" ];
      anInteger->SetValue( Component, count );
      count++;

      // Complete the designer transaction.
      t->Commit();
      if ( notification_mode )
            MessageBox::Show( "Designer-Initiated Designer Transaction Completed" );
   }

public:
   property DesignerVerbCollection^ Verbs 
   {
      // The Verbs property is overridden from ComponentDesigner
      virtual DesignerVerbCollection^ get() override
      {
         DesignerVerbCollection^ dvc = gcnew DesignerVerbCollection;
         dvc->Add( gcnew DesignerVerb( "Perform Example Transaction",gcnew EventHandler( this, &DTDesigner::DoTransaction ) ) );
         if ( notification_mode )
                  dvc->Add( gcnew DesignerVerb( "End Designer Transaction Notifications",
                     gcnew EventHandler( this, &DTDesigner::UnlinkDTNotifications ) ) );
         else
                  dvc->Add( gcnew DesignerVerb( "Show Designer Transaction Notifications",
                     gcnew EventHandler( this, &DTDesigner::LinkDTNotifications ) ) );

         return dvc;
      }
   }
   virtual void Initialize( IComponent^ component ) override
   {
      ComponentDesigner::Initialize( component );
      notification_mode = false;
      count = 10;
      IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
      if ( host == nullptr )
      {
         MessageBox::Show( "The IDesignerHost service interface could not be obtained." );
         return;
      }

      if ( MessageBox::Show( "Press the Yes button to display notification message boxes for the designer transaction opened and closed notifications.", "Link DesignerTransaction Notifications?", MessageBoxButtons::YesNo, MessageBoxIcon::Question, MessageBoxDefaultButton::Button1, MessageBoxOptions::RightAlign ) == DialogResult::Yes )
      {
         host->TransactionOpened += gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
         host->TransactionClosed += gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
         notification_mode = true;
      }
   }

public:
   ~DTDesigner()
   {
      UnlinkDTNotifications( this, gcnew EventArgs );
   }
};

// Associate the DTDesigner with this component

[DesignerAttribute(DTDesigner::typeid)]
public ref class DTComponent: public System::ComponentModel::Component
{
private:
   String^ m_String;
   int m_Count;
   void InitializeComponent()
   {
      m_String = "Initial Value";
      m_Count = 0;
   }

public:
   property String^ StringProperty 
   {
      String^ get()
      {
         return m_String;
      }

      void set( String^ value )
      {
         m_String = value;
      }
   }

   property int CountProperty 
   {
      int get()
      {
         return m_Count;
      }

      void set( int value )
      {
         m_Count = value;
      }
   }
};


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show: