Edit

Share via

Update Ribbon customizations migrated to .NET Framework 4.5

  • Article

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 or later.

  • Modify the generated Ribbon code.

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

Update the generated Ribbon code

If the target framework of your project is changed to the .NET Framework 4 or later, 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 either Visual Studio 2012 or 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 2013, 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 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 Ribbon1()
{
    InitializeComponent();
}

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

    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.

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

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

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

    For a full list of the helper methods for the Ribbon controls, see Instantiate 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 Click event in a project that targets the .NET Framework 3.5.

    <CodeContentPlaceHolder>8 In a project that targets the .NET Framework 4 or later, you must use the following code instead.

    <CodeContentPlaceHolder>9 For a full list of the Ribbon delegates, see Handle 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.

Instantiate 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 or later, 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 or later.

<CodeContentPlaceHolder>10 <CodeContentPlaceHolder>11 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 or later.

Control RibbonFactory method to use in .NET Framework 4 and later 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

Handle 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 or later, 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 or later.

Event Delegate to use in .NET Framework 4 and later projects
LoadImage event in a generated Ribbon class RibbonLoadImageEventHandler
Load RibbonUIEventHandler
Click

Click

ItemsLoading

TextChanged

ButtonClick

ItemsLoading

SelectionChanged

TextChanged

ButtonClick

Click

ItemsLoading

DialogLauncherClick

ItemsLoading

Click

Click		 RibbonControlEventHandler

Set 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 or later, 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.

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

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

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

Related content