This document covers upgrades of forms that use DotNetBarManager prior to 6.0. Other controls in suite are unaffected by this change.


If you are upgrading from the releases prior to 4.x please first upgrade to 5.9 release of DotNetBar that you can find under Previous releases on our Customer only web site. Make sure that you open DotNetBarManager designer and change any property and close it to complete the 5.9 upgrade.

Starting with 6.0 release, DotNetBarManager does not any longer use the XML based serialization for dockable windows and toolbars. Instead code-based serialization is used. DotNetBarManager dialog designer is removed and replaced with on the form toolbar, menu bar and dockable windows editing and creation.

To upgrade follow these steps for each form that is using DotNetBarManager:

  1. Create backup for your project before upgrading. There is no going back without backup.
  2. Open each form in VS.NET designer that is using DotNetBarManager and you will be asked to perform upgrade
  3. After upgrade is complete you will have to adjust the size and position of the dockable windows, possibly menus and toolbars as well
  4. If you made backup of the form save it, close it and reopen it. If you do not have backup of the form DO NOT SAVE IT.

After upgrade is complete you will have to apply some changes to your code and test to see whether everything is working correctly. In particular you need to make sure that all toolbar and menu buttons clicks are actually handled. Work through following list:

  • Search your code for usage DotNetBarManager.Items collection. If you do use it, change that code to use the actual item instance instead since Items collection will be empty. After upgrade all buttons will be available directly on the form and you can use them directly. For example if you had following line of code:
    dotNetBarManager1.Items[“bCut”].Enabled = false
    you can replace it with:
    bCut.Enabled=false
  • If you have code that is docking windows from code (does not apply to toolbars and menus) you will have to change/rewrite it since docking mechanism is completely new. Take a look at DockingFromCode sample for details of how to dock and create windows from code.
  • Search your code for usage of DotNetBarManager.GetItem method. You can now use the actual item instances instead of going through the GetItem method.
  • If you are using Command Links you will need to remove code that declares them and creates new instances. That code usually is in InitializeComponent method. Your project will not compile until these are deleted so that is handy way to find them. Command Links are no longer needed so you will need to add event handlers to the actual buttons that are created on the form and copy the event handling code from CommandLink event handler into it.
  • Check your DotNetBarManager.ItemClick event handler. If you use BaseItem.Name property to test for an item name for an easy update switch to using BaseItem.GlobalName property instead.
  • If you were using DotNetBarManager to provide context menus for your controls, the automatic update has replaced that with ContextMenuBar control. If you were relyign on Global Items feature of DotNetBarManager in regards to context menus, make sure to set DotNetBarManager.GlobalContextMenuBar property to the instance of ContextMenuBar created by the update routine so global items feature integrates with the context menu. Also read documentation for DotNetBarManager.GlobalContextMenuBar property.

BaseItem.GlobalName property has been added to enable DotNetBar Global Items feature. Since Windows Forms Designer requires unique names for each item instance, it is not possible for items to share the same name even though they perform same function. However, you can set the BaseItem.GlobalName to the same string identifier and DotNetBar will use that property when propagating the property change to all items with the same GlobalName. GlobalName is automatically set during import.

  • DotNetBarManager saved definitions that were created using DotNetBarManager.SaveDefinition with versions prior to 6.0 are not backwards compatible and will not be loaded when DotNetBarManager.LoadDefinition method is called
  • DotNetBarManager saved layouts that were created with DotNetBarManager.SaveLayout method in versions prior to 6.0 are not backwards compatible and will not be loaded when DotNetBarManager.LoadLayout is called. However, saving and loading layouts using 6.0 version will work as expected.
  • If you use DotNetBarManager.SaveDefinition and DotNetBarManager.LoadDefinition to save layout of dockable windows and toolbars switch to DotNetBarManager.SaveLayout and DotNetBarManager.LoadLayout
  • You can drag & drop the content for your dockable windows on form directly. You do not need to use ContainerLoadControl event to do so any longer.
  • You can also design your menus and toolbars directly on the form
  • To create new dockable windows and toolbars, right-click DotNetBarManager and use context menu commands to do so.
  • The DotNetBarManager.Items collection is not imported and automatic categorization of the items for customization purposes is used instead. Simply make sure that items you want exposed for customization have Category property set and CanCustomize property set appropriately. If you need to use custom categorization you will have to add items manually through code to DotNetBarManager.Items collection. In that case automatic categorization will not be used.
  • Once your upgrade is complete you can remove DotNetBarManager XML definition file from your project since it is not needed any longer.

Follow these steps if you have used DotNetBarManager context menus to upgrade

  • If you have used DotNetBarManager context menus, they have been replaced with the ContextMenuBar control that during import was automatically created
  • You will have to wire the events for each item by either double-clicking each context menu item on ContextMenuBar or by handling the ContextMenuBar.ItemClick event. You can double-click the ContextMenuBar to create event handler

Ribbon Control Updates

In 6.0 release the styling system for Ribbon Control has been updated to allow seamless switching between multiple color tables. The RibbonControl.Office2007ColorTable property has been added so you can choose the Color Table at design-time. To enable that functionality you need to reset the old color settings as described below:

  • On RibbonControl reset all properties under RibbonControl.BackgroundStyle. Right click the properties for which value appears in bold text and choose Reset or select and delete the value. Verify that BackColorBlend collection is empty as well. Same procedure applies to all items listed below.
  • On RibbonBar reset all properties under:
    BackgroundStyle,
    BackgroundMouseOverStyle
    TitleStyle
    TitleStyleMouseOver
  • On RibbonPanel reset all properties under:
    Style,
    StyleMouseOver

Related posts:

  1. Working with DotNetBar from code.
  2. How to Create Context Menus
  3. How to create Dockable Windows
  4. How to add any control to menu, toolbar and other DotNetBar controls
  5. How to set ColorScheme for context menus