Thursday, September 9, 2010

Command Method: Static Or Not Static

When starting to use AutoCAD .NET API, the very first code people would be writing is the the command method in a class, e.g. a public method decorated with [CommandMethod()] attribute. However, the command method can be either "static/Shared" (C#/VB.NET) or not "static/Shared" (instance method). Also, in most smaple code one can find, there is rarely one that show the class' constructor is used.


It also puzzles some beginners if the command method is not a "static" one: why an instance method (non-static method) can be called in command without the code creating an object instance of the class?


Here is what the AutoCAD .NET API document has to say:


[quote]
For an instance command method, the method's enclosing type is instantiated separately for each open document. This means that each document gets a private copy of the command's instance data. Thus there is no danger of overwriting document-specific data when the user switches documents. If an instance method needs to share data globally, it can do so by declaring static or Shared member variables.
For a static command method, the managed wrapper runtime module does not need to instantiate the enclosing type. A single copy of the method's data is used, regardless of the document context. Static commands normally do not use per-document data and do not require special consideration for MDI mode.
[/quote]
 
With a few lines of very simple code, we can see what the difference betweem static method and instance command method.
 
Here is the code:

using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.Runtime;

namespace CommandClassTest
{
    public class MyCommand
    {
        private static int _staticCount = 0;
        private int _instanceCount = 0;

        public MyCommand()
        {
            Document dwg = Autodesk.AutoCAD.ApplicationServices.
                Application.DocumentManager.MdiActiveDocument;
            dwg.Editor.WriteMessage("\n**************");
            dwg.Editor.WriteMessage("\nConstructing...");
            dwg.Editor.WriteMessage("\n**************");
        }

        [CommandMethod("StaticCommand", CommandFlags.Session)]
        public static void RunThisMethod1()
        {
            _staticCount++;
            Document dwg = Autodesk.AutoCAD.ApplicationServices.
                Application.DocumentManager.MdiActiveDocument;
            dwg.Editor.WriteMessage("\n----------------------------");
            dwg.Editor.WriteMessage("\n" + dwg.Name);
            dwg.Editor.WriteMessage("\nStatic command executed.");
            dwg.Editor.WriteMessage("\nStatic command count: {0}", _staticCount);
        }

        [CommandMethod("InstanceCommand", CommandFlags.Session)]
        public void RunThisMethod2()
        {
            _instanceCount++;
            Document dwg = Autodesk.AutoCAD.ApplicationServices.
                Application.DocumentManager.MdiActiveDocument;
            dwg.Editor.WriteMessage("\n----------------------------");
            dwg.Editor.WriteMessage("\n" + dwg.Name);
            dwg.Editor.WriteMessage("\nInstance command executed.");
            dwg.Editor.WriteMessage("\nInstance command count: {0}", _instanceCount);
        }
    }
}

Let's run this code in AutoCAD:

1. Start AutoCAD and "NETLOAD" to DLL;
2. With current drawing "Drawing1.dwg", enter command "InstanceCommand", the command line shows:

Command: instancecommand

**************
Constructing...
**************
----------------------------
Drawing1.dwg
Instance command executed.
Instance command count: 1

As you can see, the class' constructor is called due to the instance (non-static) command method.

3. Now, run "InstanceCommand" command again with "Drawing1.dwg". We now can guess that the constructor of the class will not run again since the class instance has already been created with this drawing (Drawing1.dwg), and the count for instance command will increment to 2. Here is the command line response, as expected:

Command: instancecommand
-------------------------------
Drawing1.dwg
Instance command executed.
Instance command count: 2

4. Let's run the static command. The command line shows:
 
Command: staticcommand
--------------------------
Drawing1.dwg
Static command executed.
Static command count: 1
 
5. Now, open a new drawing in AutoCAD: Drawing2.dwg.
6. Run the static command. we would expect the static command count to increment to 2, like this:
 
Command: staticcommand

--------------------------
Drawing2.dwg
Static command executed.
Static command count: 2

7. Run instance command in Drawing2.dwg. the command shows:
 
Command: instancecommand

**************
Constructing...
**************
----------------------------
Drawing2.dwg
Instance command executed.
Instance command count: 1


As we can see, the class' constructor is called again, because the instance command runs in drawing2.dwg the first time.
 
8. Now go back to drawing1.dwg.
9. Run static command. we surely know the static command count will be 3, in spite of drawing switching:
 
Command: staticcommand

--------------------------
Drawing1.dwg
Static command executed.
Static command count: 2

10. Run instance command in drawing1.dwg, expecting that the instance command count in drawing1.dwg will be 3 and no class' constructor is called. Here is command line shows:
 
Command: instancecommand

-------------------------------
Drawing1.dwg
Instance command executed.
Instance command count: 3

Summery:
 
If your class/class method needs to manipulate data/object accross drawings in an AutoCAD session, you use static method and the data/object can be static data/object member of the class. If your static data/object member of the class has to be initialized, you cannot do it in the class' constructor. In this case, you usually delare the static data/object to a default value/null like this:
 
private static int _count=0;
 
or
 
private static MyObject _obj=null;
 
Then, in the static command method, you do:
 
if (_count==0)
{
    //Initialize to other value if necessary
}
//then use the static data accross drawings
 
or
 
if (_obj==null)
{
    _obj=new MyObject(); //instantiate the data object if it hasn't been.
}
//the use the static object accross drawings
 
If the data/object to be manipulated by the class/class method is drawing specific, for example a drawing tracking/index data object, then you can declare the data/object as the class' data/object member (non-static), and initilize it in the class' constructor. You use instance method to manipulate the data/object

1 comment:

doug said...

great post Norman! Thanks for putting that information out here!

Followers

About Me

My photo
After graduating from university, I worked as civil engineer for more than 10 years. It was AutoCAD use that led me to the path of computer programming. Although I now do more generic business software development, such as enterprise system, timesheet, billing, web services..., AutoCAD related programming is always interesting me and I still get AutoCAD programming tasks assigned to me from time to time. So, AutoCAD goes, I go.