DesignerTransaction 類別

定義

命名空間:

System.ComponentModel.Design

組件:

System.ComponentModel.TypeConverter.dll

來源:

DesignerTransaction.cs

提供方式，用於群組一系列設計階段動作以改善效能，以及啟用大部分變更類型以復原。

public ref class DesignerTransaction abstract : IDisposable

public abstract class DesignerTransaction : IDisposable

type DesignerTransaction = class
    interface IDisposable

Public MustInherit Class DesignerTransaction
Implements IDisposable

繼承

Object

DesignerTransaction

實作

IDisposable

範例

下列程式代碼範例程式示範如何從設計工具建立 DesignerTransaction 。 若要執行此範例，請將原始程式碼編譯成類別庫。 您必須加入 System.Design 元件的參考。 在新專案中，新增已編譯 DLL 的參考，並將連結庫中的元件新增至 [工具箱]。

在Visual Studio中，這項功能有廣泛的支援。

另請參閱 逐步解說：使用自定義元件自動填入工具箱。

設計工具可以選擇性地顯示設計工具交易事件的通知。 如果您在設計模式中將 的 DTComponent 實例新增至窗體，則會出現消息框，詢問您是否要接收設計工具交易事件通知。 您可以使用以滑鼠右鍵按下 實例 DTComponent時出現的快捷方式選單來切換這些通知。 當您使用 屬性視窗 變更值時，就會建立交易。 您也可以在元件的快捷方式功能表上按兩下 [ 執行範例交易 ]，讓設計工具執行交易。

#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;
      }
   }
};

using System;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Windows.Forms;
using 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.
*/

namespace DesignerTransactionSample
{
    // Associate the DTDesigner with this component
    [DesignerAttribute(typeof(DTDesigner))]
    public class DTComponent : System.ComponentModel.Component
    {
        private string m_String;
    private int m_Count;
            
    public string StringProperty
    {
        get
            { return m_String; }
        set
        { m_String = value; }
    }
            
    public int CountProperty
    {
        get
        { return m_Count; }
        set
        { m_Count = value; }
    }

    private void InitializeComponent()
    {
        m_String = "Initial Value";
        m_Count = 0;
    }
    }
    
    internal class DTDesigner : ComponentDesigner
    {
    private bool notification_mode = false;
    private int count = 10;
        
    // The Verbs property is overridden from ComponentDesigner
    public override DesignerVerbCollection Verbs
    {
        get
        {				
            DesignerVerbCollection dvc = new DesignerVerbCollection();				
        dvc.Add( new DesignerVerb("Perform Example Transaction", new EventHandler(this.DoTransaction)) );
        if(notification_mode)
            dvc.Add(new DesignerVerb("End Designer Transaction Notifications", new EventHandler(this.UnlinkDTNotifications)));
        else
            dvc.Add(new DesignerVerb("Show Designer Transaction Notifications", new EventHandler(this.LinkDTNotifications)));				return dvc;
        }
    }
        
        public override void Initialize(System.ComponentModel.IComponent component)
        {
            base.Initialize(component);

            IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));			
            if(host == null)
            {
                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 += new EventHandler(OnDesignerTransactionOpened);
                host.TransactionClosed += new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
                notification_mode = true;
            }
        }
        
        private void LinkDTNotifications(object sender, EventArgs e)
        {
            if(notification_mode == false)
            {
            IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));							
                if(host != null)
            {
            notification_mode = true;
                   host.TransactionOpened += new EventHandler(OnDesignerTransactionOpened);
                   host.TransactionClosed += new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
            }
        }
        }

        private void UnlinkDTNotifications(object sender, EventArgs e)
        {
        if(notification_mode)
            {
                IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));							
            if(host != null)
                {				
            notification_mode = false;
                    host.TransactionOpened -= new EventHandler(OnDesignerTransactionOpened);
                    host.TransactionClosed -= new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
                }
            }
        }

        private void OnDesignerTransactionOpened(object sender, EventArgs e)
        {			
        System.Windows.Forms.MessageBox.Show("A Designer Transaction was started. (TransactionOpened)");
        }

        private void OnDesignerTransactionClosed(object sender, DesignerTransactionCloseEventArgs e)
        {			
        System.Windows.Forms.MessageBox.Show("A Designer Transaction was completed. (TransactionClosed)");
        }   

        private void DoTransaction(object sender, EventArgs e) 
        {			
            IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));			
            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. */
            using (t)
            {
            if(notification_mode)
                System.Windows.Forms.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)
                System.Windows.Forms.MessageBox.Show("Designer-Initiated Designer Transaction Completed");
            }
        }
        
    protected override void Dispose(bool disposing)
    {
        UnlinkDTNotifications(this, new EventArgs());
        base.Dispose(disposing);
    }
    }
}

Imports System.ComponentModel
Imports System.ComponentModel.Design
Imports System.Windows.Forms
Imports 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 are being 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.	

Namespace DesignerTransactionSample

    ' Associate the DTDesigner with this component
    <DesignerAttribute(GetType(DTDesigner))> _
    Public Class DTComponent
        Inherits System.ComponentModel.Component
        Private m_String As String
        Private m_Count As Integer

        Public Property StringProperty() As String
            Get
                Return m_String
            End Get
            Set(ByVal Value As String)
                m_String = Value
            End Set
        End Property

        Public Property CountProperty() As Integer
            Get
                Return m_Count
            End Get
            Set(ByVal Value As Integer)
                m_Count = Value
            End Set
        End Property

        Private Sub InitializeComponent()
            m_String = "Initial Value"
            m_Count = 0
        End Sub

    End Class

    Friend Class DTDesigner
        Inherits ComponentDesigner

        Private notification_mode As Boolean = False
        Private count As Integer = 10

        ' The Verbs property is overridden from ComponentDesigner
        Public Overrides ReadOnly Property Verbs() As DesignerVerbCollection
            Get
                Dim dvc As New DesignerVerbCollection()
                dvc.Add(New DesignerVerb("Perform Example Transaction", AddressOf Me.DoTransaction))
                If notification_mode Then
                    dvc.Add(New DesignerVerb("End Designer Transaction Notifications", AddressOf Me.UnlinkDTNotifications))
                Else
                    dvc.Add(New DesignerVerb("Show Designer Transaction Notifications", AddressOf Me.LinkDTNotifications))
                End If
                Return dvc
            End Get
        End Property

        Public Overrides Sub Initialize(ByVal component As System.ComponentModel.IComponent)
            MyBase.Initialize(component)

            Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
            If host Is Nothing Then
                MessageBox.Show("The IDesignerHost service interface could not be obtained.")
                Return
            End If

            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 Then
                AddHandler host.TransactionOpened, AddressOf OnDesignerTransactionOpened
                AddHandler host.TransactionClosed, AddressOf OnDesignerTransactionClosed
                notification_mode = True
            End If
        End Sub

        Private Sub LinkDTNotifications(ByVal sender As Object, ByVal e As EventArgs)
            If notification_mode = False Then
                Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
                If (host IsNot Nothing) Then
                    notification_mode = True
                    AddHandler host.TransactionOpened, AddressOf OnDesignerTransactionOpened
                    AddHandler host.TransactionClosed, AddressOf OnDesignerTransactionClosed
                End If
            End If
        End Sub

        Private Sub UnlinkDTNotifications(ByVal sender As Object, ByVal e As EventArgs)
            If notification_mode Then
                Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
                If (host IsNot Nothing) Then
                    notification_mode = False
                    RemoveHandler host.TransactionOpened, AddressOf Me.OnDesignerTransactionOpened
                    RemoveHandler host.TransactionClosed, AddressOf Me.OnDesignerTransactionClosed
                End If
            End If
        End Sub

        Private Sub OnDesignerTransactionOpened(ByVal sender As Object, ByVal e As EventArgs)
            System.Windows.Forms.MessageBox.Show("A Designer Transaction was started. (TransactionOpened)")
        End Sub

        Private Sub OnDesignerTransactionClosed(ByVal sender As Object, ByVal e As DesignerTransactionCloseEventArgs)
            System.Windows.Forms.MessageBox.Show("A Designer Transaction was completed. (TransactionClosed)")
        End Sub

        Private Sub DoTransaction(ByVal sender As Object, ByVal e As EventArgs)
            Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
            Dim t As DesignerTransaction = 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. 
            Try
                If (notification_mode) Then
                    System.Windows.Forms.MessageBox.Show("Entering a Designer-Initiated Designer Transaction")
                End If

                Dim someText As PropertyDescriptor = TypeDescriptor.GetProperties(Component)("StringProperty")
                someText.SetValue(Component, "This text was set by the designer for this component.")
                Dim anInteger As PropertyDescriptor = TypeDescriptor.GetProperties(Component)("CountProperty")
                anInteger.SetValue(Component, count)
                count = count + 1

                Exit Try
            Finally
                t.Commit()                
            End Try
            If (notification_mode) Then
                System.Windows.Forms.MessageBox.Show("Designer-Initiated Designer Transaction Completed")
            End If
        End Sub

        Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
            UnlinkDTNotifications(Me, New EventArgs())
            MyBase.Dispose(disposing)
        End Sub

    End Class
End Namespace 'DesignerTransactionSample

備註

交易可以追蹤稍後可以復原的動作。 在交易期間所做的變更可以藉由取消交易來反轉，藉由將每個變更屬性設定為其變更前值，以自動嘗試反轉每個變更。 交易也可以藉由將更新延遲到交易完成，以改善一系列作業期間的效能。

當交易正在進行時，某些元件會延遲其處理，直到交易完成為止，方法是接聽 TransactionOpening 和 TransactionClosed 事件。 例如，屬性視窗 不會在交易開啟之後更新其顯示，直到交易關閉為止。

若要針對可反轉或多個作業使用交易，請讓設計工具針對每個作業或一系列應該可復原的作業建立 DesignerTransaction 。 請小心不要在交易外部執行動作，以防止一連串復原事件順利完成。

您可以呼叫 CreateTransaction 的 IDesignerHost方法，以取得新的 DesignerTransaction 。 請務必從使用IDesignerHost中取得每個 DesignerTransaction ，以便與設計工具事務處理機制正確整合，而不是直接建立新的 DesignerTransaction 。

若要在交易內執行動作，您必須先建立交易。 然後，您必須在每個變更或變更集發生之前呼叫 OnComponentChanging 方法，並在 OnComponentChanged 每次變更或變更集之後呼叫 方法。 最後，呼叫 Commit 方法來完成並關閉交易。

注意

對屬性值進行變更時，請使用 SetValue 的 PropertyDescriptor方法，它會呼叫 的 IComponentChangeService 元件變更方法，並建立 DesignerTransaction 代表自動變更的 。

若要執行交易，請完成下列步驟：

1. 呼叫 CreateTransaction 以取得 DesignerTransaction 可用來控制交易的 。

2. 在 try 區塊內，針對您想要追蹤 DesignerTransaction的每個動作，呼叫 OnComponentChanging 方法、進行變更或變更，然後呼叫 OnComponentChanged 方法以發出變更或變更的訊號。

3. 若要完成交易，請從 區塊內finally呼叫 Commit 。

在 C# 中，您可以使用 using 語句而非 try/finally 區塊，例如在下列範例中。

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

若要在認可交易之前取消並嘗試回復交易，請呼叫 Cancel 方法。 Cancel叫用 方法時，會反轉 所追蹤DesignerTransaction的動作，以嘗試復原變更。 若要復原在先前交易期間發生的動作，您必須使用開發環境所提供的復原命令。

建構函式

DesignerTransaction()	不使用描述，初始化 DesignerTransaction 類別的新執行個體。
DesignerTransaction(String)	使用指定的異動描述，初始化 DesignerTransaction 類別的新執行個體。

屬性

Canceled	取得值，表示異動是否已取消。
Committed	取得值，表示異動是否已認可。
Description	取得異動的描述。

方法

Cancel()	取消異動，並嘗試復原異動事件所做的變更。
Commit()	認可這個異動。
Dispose(Boolean)	釋放 DesignerTransaction 所使用的 Unmanaged 資源，並選擇性地釋放 Managed 資源。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
Finalize()	釋出與這個物件相關聯的資源。 如果這個異動還沒有認可，則這個覆寫會認可該異動。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
OnCancel()	引發 Cancel 事件。
OnCommit()	執行認可異動的實際工作。
ToString()	傳回代表目前物件的字串。 (繼承來源 Object)

明確介面實作

IDisposable.Dispose()

釋放 DesignerTransaction 所使用的所有資源。

另請參閱

• IDesignerHost
• IComponentChangeService
• PropertyDescriptor