Plug-In Migration Steps

We discussed the migration of The Building Coder samples from the Revit 2010 to the Revit 2011 API and noted some of the required steps there, but skipped a lot of the obvious and onerous detailed information. Luckily, my colleague Joe Ye was more patient and precise when he migrated our Revit Structure labs and analysis link sample, and kept track of the required steps in great detail. So, without further ado, here are Joe's Revit 2011 plug-in project migration notes:

Steps to migrate Revit 2010 code to Revit 2011

Before migrating the code, please read the What's New section in the Revit API help file RevitAPI.chm file to know what happened in the API. Then follow below steps.

1. Open the Revit code project in Visual Studio 2008.
2. Remove the reference to old Revit API assembly RevitAPI.dll.
3. Reference the new Revit API assemblies RevitAPI.dll and RevitAPIUI.dll, which are located in the Revit 2011 installation Program subfolder.
4. Replace old namespaces with the new ones, for example:

   //using Autodesk.Revit;
   //using Autodesk.Revit.Elements;
   //using Autodesk.Revit.Structural.Enums;
   using Autodesk.Revit.ApplicationServices;
   using Autodesk.Revit.Attributes;
   using Autodesk.Revit.DB;
   using Autodesk.Revit.UI;
   

   All namespace mappings are documented in 'Revit 2011 API Namespace Remapping.xlsx' file in SDK.
5. Decide what regeneration option and transaction mode are required for the external command or application classes. This is a non-trivial decision, cf. manual regeneration option risks and best practices.
6. Add the regeneration option and transaction mode attributes, e.g.

   [Transaction( TransactionMode.ReadOnly )]
   [Regeneration( RegenerationOption.Manual )]
   

7. If you have used full class names, change the namespace of the IExternalCommand or IExternalApplication interfaces, ExternalCommandData class, and Result enumeration to Autodesk.Revit.UI.
8. The way to access the Application and Document instances changed. The command data argument now returns a new UIApplication class instance. Use the following code to access the database level application and active document objects:

   UIApplication uiapp = commandData.Application;
   UIDocument uidoc = uiapp.ActiveUIDocument;
   Application app = uiapp.Application;
   Document doc = uidoc.Document;
   

   In Revit 2010, there was no separation between the user interface and database level application and document objects. The application was accessed through the ExternalCommandData.Application property, and the active document through ExternalCommandData.Application.Document.
9. If the project has element iteration processes, you need to migrate these to use the new FilteredElementCollector class. Please refer to RevitAPI.chm and Revit 2011 API developer guide.pdf for detailed information.
10. Some classes were renamed. Please read the What's New section in RevitAPI.chm for detailed information, and replace the old class names with the ones.

Other notes

1. Creating a new ElementId instance requires an argument, unlike Revit 2010.
2. The Document get_Element( ElementId ) method now takes an ElementId argument without the ref keyword, because ElementId is a class now.
3. TypeFilter changed to ElementClassFilter. Creating instance change to use New ElementClassFilter
4. CategoryFilter becomes ElementCategoryFilter. Other element filter class are also renamed.
5. Access to the Revit Structure analytical model changed.
6. The ElementId Value property changed to IntegerValue, so replace with the new property name.
7. When retrieving document elements, we need to set a filter explicitly. If no filter was set at all, an exception is thrown.
8. If the command is using the manual regeneration option and the code makes changes to the model, we need to explicitly create a transaction to update the model:

   Transaction t = new Transaction(
     doc, "Test" );
   
   t.Start();
   
   . . .
   
   t.Commit();
   

9. Some other detailed items are not listed here. Please refer to the API changes documentation for further information.

Many thanks to Joe for these detailed instructions!