Using .NET assembly attributes

 
 
 

In the .NET SDK of Maya, .NET assembly attributes are used to auto-register plug-ins, commands, nodes and so forth. This is different from the C++ SDK of Maya, where the MFnPlugin class provides registration methods for all MPx-prefixed classes of Maya (MPxCommand, MPxNode, and so forth). In .NET, classes are instead decorated with attributes which are parsed by the plug-in loader, which registers them with Maya on your behalf.

Refer to the MFnPlugin class reference documentation for more information.

Extension Plugin

Specify the ExtensionPlugin assembly attribute in your plug-in.

In general, add this assembly attribute at the top of the class that defines your plug-in:

[assembly: ExtensionPlugin(typeof(PluginClass), "Name1", "Name2",…)]

where:

This attribute is not mandatory; but, if specified, speeds up the loading of your plug-in. Otherwise, Maya searches for the first C# class that implements the IExtensionPlugin interface. This interface contains the following methods:

bool InitializePlugin () ; // called when the plug-in is loaded

bool UninitializePlugin () ; // called when the plug-in is unloaded

System::String^ GetMayaDotNetSdkBuildVersion(); //Returns a string representation of the integer version of Maya (for example, “20135002”)

Commands

Command definition

[assembly: MPxCommandClass(typeof(MPxCommandDerivedClass), "CommandName")]

where:

  • MPxCommandClass: This attribute ensures that the command class is registered in Maya.
  • MPxCommandDerivedClass: The name of your C# class that derives from MPxCommand.

    You need to specify the full path, including the class namespace.

  • CommandName: the name of the command as it appears in Maya’s Script Editor.

Example as follows:

[assembly: MPxCommandClass(typeof(MayaNetTest.WhatIsCmd), "netWhatIs")]
namespace MayaNetTest 
{
    public class WhatIsCmd : MPxCommand, IMPxCommand 
    {
        override public void doIt(MArgList args)
        {
            …
        }
    }
}

Command syntax

You may also need some class attributes (located above the definition of your command class) to describe the syntax of your command.

The following are the various attributes you can specify.

Command arguments

If your command takes arguments, you need to add the following attribute for each argument:

[MPxCommandSyntaxArg(typeof(ArgType))]

  • MPxCommandSyntaxArg: This attribute ensures that this argument is added to the syntax.

  • ArgType: The type of the argument (for example: System.String).

The following is an example:

[MPxCommandSyntaxArg(typeof(System.String))] // a string argument
[MPxCommandSyntaxArg(typeof(System.Int32))] // an integer argument

In the case where the argument is an object, you should use this class attribute with more controls:

[MPxCommandSyntaxSelection( UseSelectionAsDefault = UseSelection,  MinObjectCount = min, MaxObjectCount = max, ObjectsType = typeof(ObjType))]

where:

  • MPxCommandSyntaxSelection: This attribute ensures that this argument is added to the syntax.
  • UseSelection: Whether the command uses the selection if no object is specified.
  • min: The minimum number of objects the user can specify.
  • max: The maximum number of objects the user can specify.

ObjType can be:

  • typeof(MSelectionList): Always use the selection.
  • typeof(System.String): The user specifies the object using its name.

Here is an example:

[MPxCommandSyntaxSelection(UseSelectionAsDefault = true, MinObjectCount = 1, 
MaxObjectCount = 2, ObjectsType = typeof(System.String))]

This command accepts 1 or 2 objects and uses the selection if no object is specified.

Command flags

If your command takes one or more flags, then you must add the following class attribute for each flag.

[MPxCommandSyntaxFlag( “flag’s short name“, “flag’s long name”, Arg1 = typeof(ArgType), Arg2 = typeof(ArgType), ... ]

where:

  • MPxCommandSyntaxFlag: This attribute ensures that the flag is added to the syntax of the command.
  • flag’s short name: The short name for the flag (for example: -i).
  • flag’s long name: The long name for the flag (for example: -index).
  • ArgType: The type of the flag argument, if any (for example: System.Double).

Here is an example:

[MPxCommandSyntaxFlag("-na", "-name", Arg1=typeof(System.String))]
[MPxCommandSyntaxFlag("-ip", "-inPosition", 
Arg1 = typeof(System.Double), 
Arg2 = typeof(System.Double), 
Arg3 = typeof(System.Double))]
NoteThe flags -c, -q and -e are reserved for the command mode (see Command Mode).

Command Mode

Maya commands can be used in three different modes: create, query and edit.

  • Create: the command is used to create elements (default)
  • Query: the command is used with the –q flag to query elements already created.
  • Edit: the command is used with the –e flag to modify elements that have already been created.

The creation mode is always supported and is the default mode. In addition to the creation mode, commands can support the query or/and the edit mode.

You can specify the different modes using the following class attribute:

[MPxCommandSyntaxMode(CommandMode)]

Where:

  • MPxCommandSyntaxMode: This attribute ensures that the mode is set properly in the command syntax.
  • CommandMode:
    • MPxCommandSyntaxModeAttribute.CommandMode.kNone: The command only supports the creation mode.
    • MPxCommandSyntaxModeAttribute.CommandMode.kQuery: The command only supports the creation and query modes
    • MPxCommandSyntaxModeAttribute.CommandMode.kEdit: The command only supports the creation and edit modes.
    • MPxCommandSyntaxModeAttribute.CommandMode.kBoth: The command supports all three modes.

Example:

[MPxCommandSyntaxMode(MPxCommandSyntaxModeAttribute.CommandMode.kQuery)]

This command supports the creation (default) and the query mode (-q).

Retrieving the arguments and flags from your command

Use the syntax() method in a command to retrieve the arguments and flags using the MArgDatabase class.

Consider a command with the following syntax attributes:

[MPxCommandSyntaxFlag("-i", "-index")]
[MPxCommandSyntaxSelection(MinObjectCount = 1, MaxObjectCount = 1, ObjectsType = typeof(MSelectionList))]
[MPxCommandSyntaxModeAttribute(MPxCommandSyntaxModeAttribute.CommandMode.kNone)]

You could retrieve the arguments as follows:

bool isIndex;
MxPlug fPlug;
               
const string kIndexFlag = "-i" ;
const string kIndexFlagLong = "-index" ;

// the following transfers all the class attributes information 
var argData = new MArgDatabase( syntax(), args);

if ( argData.isFlagSet (kIndexFlag) )
    isIndex =true ;

// Get the plug specified on the command line.
var slist = argData.getObjects() as MSelectionList;