Updating Ribbon Customizations in Office Projects that You Migrate to the .NET Framework 4

If your project contains a Ribbon customization that was created by using the Ribbon (Visual Designer) project item, you must make the following changes to your project code if the target framework is changed to the .NET Framework 4:

• Modify the generated Ribbon code.

• Modify any code that instantiates Ribbon controls at runtime, handles Ribbon events, or sets the position of a Ribbon component programmatically.

Updating the Generated Ribbon Code

If the target framework of your project is changed to the .NET Framework 4, you must change the generated code for the Ribbon item by performing the following steps. The code files you need to update depend on the programming language and how you created the project:

• In Visual Basic projects, or in Visual C# projects that you created in Visual Studio 2010, perform all of the steps in the Ribbon code-behind file (YourRibbonItem.Designer.cs or YourRibbonItem.Designer.vb). To see the code-behind file in Visual Basic projects, click the Show All Files button in Solution Explorer.

• In Visual C# projects that you created in Visual Studio 2008 and then upgraded to Visual Studio 2010, perform the first two steps in the Ribbon code file (YourRibbonItem.cs or YourRibbonItem.vb), and perform the remaining steps in the Ribbon code-behind file.

To change the generated Ribbon code

1. Modify the declaration of the Ribbon class so that it derives from Microsoft.Office.Tools.Ribbon.RibbonBase instead of Microsoft.Office.Tools.Ribbon.OfficeRibbon.

2. Modify the constructor of the Ribbon class as shown below. If you have added any of your own code to the constructor, do not change your code. In Visual Basic projects, modify only the parameterless constructor. Ignore the other constructor.

   The following code example shows the default constructor of a Ribbon class in a project that targets the .NET Framework 3.5.

   Public Sub New()
       MyBase.New()
       InitializeComponent()
   End Sub
   

   public Ribbon1()
   {
       InitializeComponent();
   }
   

   The following code example shows the default constructor of a Ribbon class in a project that targets the .NET Framework 4.

   Public Sub New()
       MyBase.New(Globals.Factory.GetRibbonFactory())
       InitializeComponent()
   End Sub
   

   public Ribbon1()
       : base(Globals.Factory.GetRibbonFactory())
   {
       InitializeComponent();
   }
   

3. In the InitializeComponent method, modify any code that constructs a Ribbon control so that the code instead uses one of the helper methods of the RibbonFactory object.

   Note

   In Visual C# projects, you must expand the region that is named Component Designer generated code to see the InitializeComponent method.

   For example, assume that your file contains the following line of code that instantiates a RibbonButton named button1 in a project that targets the .NET Framework 3.5.

   Me.button1 = New Microsoft.Office.Tools.Ribbon.RibbonButton()
   

   this.button1 = new Microsoft.Office.Tools.Ribbon.RibbonButton();
   

   In a project that targets the .NET Framework 4, you must use the following code instead.

   Me.button1 = Me.Factory.CreateRibbonButton()
   

   this.button1 = this.Factory.CreateRibbonButton();
   

   For a full list of the helper methods for the Ribbon controls, see Instantiating Ribbon Controls.

4. In Visual C# projects, modify any line of code in the InitializeComponent method that uses an EventHandler<TEventArgs> delegate to use a specific Ribbon delegate instead.

   For example, assume that your file contains the following line of code that handles the RibbonButton.Click event in a project that targets the .NET Framework 3.5.

   this.button1.Click += new System.EventHandler<Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>(
       this.button1_Click);
   

   In a project that targets the .NET Framework 4, you must use the following code instead.

   this.button1.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(
       this.button1_Click);
   

   For a full list of the Ribbon delegates, see Handling Ribbon Events.

5. In Visual Basic projects, locate the ThisRibbonCollection class at the end of the file. Modify the declaration of this class so that it no longer inherits from Microsoft.Office.Tools.Ribbon.RibbonReadOnlyCollection.

Instantiating Ribbon Controls

You must modify any code that dynamically instantiates Ribbon controls. In projects that target the .NET Framework 3.5, Ribbon controls are classes that you can instantiate directly in certain scenarios. In projects that target the .NET Framework 4, these controls are interfaces that you cannot instantiate directly. You must create the controls by using methods that are provided by the RibbonFactory object.

There are two ways to access the RibbonFactory object:

• By using the Factory property of the Ribbon class. Use this approach from code in your Ribbon class.

• By using the Globals.Factory.GetRibbonFactory method. Use this approach from code outside your Ribbon class. For more information about the Globals class, see Global Access to Objects in Office Projects.

The following code example demonstrates how to create a RibbonButton in a Ribbon class in a project that targets the .NET Framework 4.

Dim button As Microsoft.Office.Tools.Ribbon.RibbonButton =
    Me.Factory.CreateRibbonButton()

Microsoft.Office.Tools.Ribbon.RibbonButton button =
    this.Factory.CreateRibbonButton();

The following table lists the controls you can create programmatically and the method to use to create the controls in projects that target the .NET Framework 4.

Control	RibbonFactory method to use in .NET Framework 4 projects
RibbonButton	CreateRibbonButton
RibbonButtonGroup	CreateRibbonButtonGroup
RibbonCheckBox	CreateRibbonCheckBox
RibbonComboBox	CreateRibbonComboBox
RibbonDialogLauncher	CreateRibbonDialogLauncher
RibbonDropDown:	CreateRibbonDropDown
RibbonDropDownItem	CreateRibbonDropDownItem
RibbonEditBox	CreateRibbonEditBox
RibbonGallery	CreateRibbonGallery
RibbonGroup	CreateRibbonGroup
RibbonLabel	CreateRibbonLabel
RibbonManager	CreateRibbonManager
RibbonMenu	CreateRibbonMenu
RibbonSeparator	CreateRibbonSeparator
RibbonSplitButton	CreateRibbonSplitButton
RibbonTab	CreateRibbonTab
RibbonToggleButton	CreateRibbonToggleButton

Handling Ribbon Events

You must modify any code that handles events of Ribbon controls. In projects that target the .NET Framework 3.5, these events are handled by the generic EventHandler<TEventArgs> delegate. In projects that target the .NET Framework 4, these events are now handled by other delegates.

The following table lists the Ribbon events and the delegates that are associated with them in projects that target the .NET Framework 4.

Event	Delegate to use in .NET Framework 4 projects
LoadImage event in a generated Ribbon class	RibbonLoadImageEventHandler
Load	RibbonUIEventHandler
RibbonButton.Click RibbonCheckBox.Click RibbonComboBox.ItemsLoading RibbonComboBox.TextChanged RibbonDropDown.ButtonClick RibbonDropDown.ItemsLoading RibbonDropDown.SelectionChanged RibbonEditBox.TextChanged RibbonGallery.ButtonClick RibbonGallery.Click RibbonGallery.ItemsLoading RibbonGroup.DialogLauncherClick RibbonMenu.ItemsLoading RibbonSplitButton.Click RibbonToggleButton.Click	RibbonControlEventHandler

Setting the Position of a Ribbon Component Programmatically

You must modify any code that sets the position of Ribbon groups, tabs, or controls. In projects that target the .NET Framework 3.5, you can use the AfterOfficeId and BeforeOfficeId methods of the static Microsoft.Office.Tools.Ribbon.RibbonPosition class to assign the Position property of a group, tab, or control. In projects that target the .NET Framework 4, you must access these methods by using the RibbonPosition property provided by the RibbonFactory object.

There are two ways to access the RibbonFactory object:

• By using the Factory property of the Ribbon class. Use this approach from code in your Ribbon class.

• By using the Globals.Factory.GetRibbonFactory method. Use this approach from code outside your Ribbon class. For more information about the Globals class, see Global Access to Objects in Office Projects.

The following code example demonstrates how to set the Position property of a tab in a Ribbon class in a project that targets the .NET Framework 3.5.

Me.tab1.Position = RibbonPosition.AfterOfficeId("TabHome")

this.tab1.Position = RibbonPosition.AfterOfficeId("TabHome");

The following code example demonstrates the same task in a project that targets the .NET Framework 4.

Me.tab1.Position = Me.Factory.RibbonPosition.AfterOfficeId("TabHome")

this.tab1.Position = this.Factory.RibbonPosition.AfterOfficeId("TabHome");

See Also

Concepts

Migrating Office Solutions to the .NET Framework 4

Ribbon Designer