AutoCode quickstart

In this Walkthrough, you will learn different features of AutoCode command templates that will help you understand the potential of AutoCode code generation.

The major steps for this walkthrough are as follows:

• Hello World Example - to understand a simple command
• Using Arguments - to generate parameterized code
• Specifying Where to Insert Code - beginning of current method, end of the class, etc.
• Multiple Code Insertion in Different Positions - for code surround and more
• Cursor Positioning - after the code is generated
• Code Formatting - to maintain document well formated

Hello World Example

The following is a simple command that generates "Hello World!" in the current edition position.

<?xml version="1.0"?> 
<Commands xmlns="http://schemas.devprojects.net/AutoCode/v3.0"> 
  <Command name="HelloWorld"> 

    <CommandBehavior> 
      <CommandLine shortcut="hw" /> 
    </CommandBehavior> 

    <CommandCode language="csharp"> 

      <Codes> 
        <Code> 
          Console.WriteLine( "Hello World!" ); 
        </Code> 
      </Codes> 

    </CommandCode> 

  </Command> 
</Commands> 

The key elements of this command are:

<Command name="HelloWorld">
The name of the command as will be show in the AutoCode Catalog.

<CommandLine shortcut="hw" />
The shortcut to invoke the command.

<Code> 
  Console.WriteLine( “Hello World!” ); 
</Code>
The literal code that will be generated.

Using Arguments

To make this command more useful lets parameterize the code changing the literal “Hello World!” to an input parameter.

<Code> <![CDATA[ 
  Console.WriteLine( “Hello <%=args[0]%>!” ); 
  ]]> 
</Code>

Note that we escaped the Code with <![CDATA[]]> because of the ‘<’ and ‘>’ characters.

Now, if we press Ctrl+Enter and then write “Summer hw” we generate this.

Console.WriteLine(“Hello Summer!”);

Invoking an AutoCode command is similar to invoking an application from a command prompt, although in AutoCode the shortcut usually goes at the end of the line like in the following example:

arg0 arg1 arg2 argN shortcut

Shortcut Position

By default, shortcut goes at the end of the command line. The reason for this is not to mess up with Intellisense and let it suggest the correct key words. If the shortcut were the first word, intellisense won’t be able to help us.

Anyway, if we want the shortcut to go first, we still can declare the command as follows.

<CommandLine shortcut="hw" shortcutPosition="First" />

And now we can invoke our command as “hw Summer” instead.

Arguments Delimiter

By default, arguments are separated by a space character.

This is the preferred for most of the commands, but there are some cases were we want to change this.

For example, in our HelloWorld command  we may want to use spaces inside the argument but that will be interpreted as different arguments. To instruct our command to use the literal as a single argument we can specify a different argument delimiter as follows.

<CommandLine shortcut="hw" shortcutPosition="First" delimiter="#" />

Now, we can write:

Summer, how are you hw <Ctrl+Enter>

And will generate:

Console.WriteLine(“Hello Summer, how are you!”);

Note that we still can use more that one argument using ‘#’ as the argument delimiter.

Specifying Where Insert the Code

By default, generated code is inserted in the current position.

To insert the code in, for example, the beginning of the document, we can specify the following:

<Codes> 
    <Code codeElement="Document" codePoint="StartOfDocument"> 
        <![CDATA[using <%=args[0]%>;]]> 
    </Code> 
</Codes>

This will generate a using statement at the beginning of the document, while the edit position will remain in the current position.

The codeElement attribute specify which element (Document, Class, Method, etc.) while the codePoint specify where in the element to insert the code (StartofDocument, StartOfBody, EndOfElement, etc.);

Here are some other combinations.

Beginning of the class code 
<Code codeElement="Class" codePoint="StartOfBody">
 
Before the Property declaration, just in the attributes decoration 
<Code codeElement="Property" codePoint=" StartOfAttributes">
 
Beginning of the Selected text (the default) 
<Code codeElement="Selection" codePoint="StartOfSelection">
 
End of the Selected text (usefull for code surround) 
<Code codeElement="Selection" codePoint="EndOfSelection"> 

Multiple Code Insertions in Different Positions

We can generate different piece of code and insert it in different positions.

For example, to surround the current selection we will want to insert code at the beginning of the selected text and at the end of the selected text.

The following example surrounds the selected code with an IF THEN sentence in VB.NET.

<Code codeElement="Selection" codePoint="StartOfElement"> 
    If Then 
</Code> 
<Code codeElement="Selection" codePoint="EndOfElement"> 
    End If 
</Code>

Referencing Generated Code

Sometimes we will want to reference generated code position, for example, to set the cursor position at the beginning of the generated code or even to insert more code at the end.

The ID attribute of the <Code> element identify the code. For example:

<Code id=”BeginIF”> 
    If Then 
</Code> 
<Code id=”EndIF”> 
    End If 
</Code>

Now we can reference “BeginIF” or “EndIF” as codeElements. For example:

<Code codeElement="BeginIF" codePoint="EndOfElement"> 
    ‘ This will be inserted between “IF Then” and “End If” 
</Code>

Also we can reference “BeginIF” or “EndIF” to position the cursor after the code insertion as described below.

Cursor Positioning

To position the cursor in a specific location after the code generation we can use the <Selection> tag.

The <Selection> tag uses the codeElement and codePoint attributes in a similar way as the <Code> tag.

For example, to position the cursor at the beginning of the “BeginIF” code:

<Selection codeElement="BeginIF" codePoint="StartOfElement" />

If we want to move the cursor inside the generated code we can use the <SelectText> attribute as follows:

<Selection codeElement="BeginIF" codePoint="StartOfElement"> 
    <SelectText>Then</SelectText> 
</Selection>

This will select the word “Then” of the generated code. Actually, we are instructing AutoCode to position the cursor at the beginning of the “BeginIF” and search for the word “Then” and select it.

The trick to position the cursor exactly where we want is to generate a mark word and select that mark. For example:

<Code id=”BeginIF”> 
    If SELECT_THIS Then 
</Code> 
<Selection codeElement="BeginIF" codePoint="StartOfElement"> 
    <SelectText>SELECT_THIS</SelectText> 
</Selection>

Finally, to hide our trick we can clear the selection with the clearSelection attribute so our mask SELECT_THIS won’t show.

<Selection codeElement="BeginIF" codePoint="StartOfElement"  clearSelection="true"> 
    <SelectText>SELECT_THIS</SelectText> 
</Selection> 

Formatting Code

When using multiple code insertions the generated code may appear unformatted. To avoid this the <SmartFormat> element can be used.

The following example will format the code from the beginning of the generated code identify as “BeginIF” to the end of the generated code “EndIF”.

<SmartFormat> 
    <Start codeElement="BeginIF" codePoint="StartOfElement" /> 
    <End codeElement="EndIF" codePoint="EndOfElement" /> 
</SmartFormat> 

If the code is inserted in different parts of the current function or class we can always specify the whole function or class:

<SmartFormat> 
    <Start codeElement="Class" codePoint="StartOfElement" /> 
    <End codeElement="Class" codePoint="EndOfElement" /> 
</SmartFormat> 

This will format the whole Class after the code generation.

Next Steps

After this Walkthrough you may be interested in creating your own commands and test different concepts explained here.

The fastest way to create your custom command is using the Command Generation Wizard.

The Command Generation Wizard is just a built in command (AX) that can be invoked as usual pressing Ctrl+Enter and specifying the name and shortcut of the command. For example:

1. Press Ctrl+Enter
2. Input “HelloWorld hw AX” in the input box
3. Press enter

Creating Custom Commands

Commands in AutoCode are xml files that can be created using any xml editor.

You can create a new command from scratch or you can use the built in command wizard "AutoX" to create a simple command.

To create a command using "AutoX" command follow these steps:

1. Open a document text
2. Press Ctrl+Enter (the AutoCode input box will appear)
3. Input the name you will give to the new command and the shortcut you will use to invoke the command, followed by "AX".
   For example: "HelloWorld hw AX"
4. This will create and open the command in a new document window for edit
5. Edit the <Code> element to insert the text you want to generate when invoking the command
6. You can also edit the <CommandInfo> element to describe and categorize your command
7. Save the file and the command will be ready to be used

The following is an example of a command created using AutoX command wizard.

<?xml version="1.0"?>
<Commands xmlns="http://schemas.devprojects.net/AutoCode/v3.0">
  <Command name="HelloWorld" priority="50">
    <CommandBehavior>
      <CommandLine shortcut="hw" />
      <ActiveDocument extensions="*"/>
    </CommandBehavior>

    <CommandInfo>
      <LanguageCategory>Common</LanguageCategory>
      <Category>(Local)</Category>
      <Usage>hw</Usage>
      <Description>No description supplied.</Description>
      <Author>Me</Author>
      <HelpUrl></HelpUrl>
    </CommandInfo>

    <CommandCode language="csharp">

      <Codes>
        <Code id="Code1">
          <![CDATA[]]>
        </Code>
      </Codes>

      <Selection codeElement="Code1" codePoint="StartOfElement">
        <SelectText></SelectText>
      </Selection>

    </CommandCode>
  </Command>
</Commands>

For instance, to generate "Hello Word!" edit the <Code> element as follow:

      <Codes>
        <Code id="Code1">
          Hello World!
        </Code>
      </Codes>

Save the file and the command will be ready to use.

The command will be saved in /My Documents/AutoCode 2008/Commands folder, and will be available for all solution for the current user.

You can also create a command in the current Solution Folfer using "AXL" command instead of "AX". The command located in the current solution will be available only for the current solution.

To test the command, open a new document, press Ctrl+Enter and input "hw" in the AutoCode input box. This will insert "Hello World!" in the current position.

 

Executing Custom Actions with AutoCode

One of the main features of AutoCode is generating in-line code. But AutoCode can also be used to execute IDE actions in a quick and easy way. For example, commenting a piece of code, formatting the current document or opening any of the multiple Visual Studio Windows (Error List, Immediate Window, Test Results, etc.) are tasks that can be executed using AutoCode instead of using the mouse through the IDE menu.

Although many of these tasks can be invoked using shortcuts, these shortcuts are not always very intuitive and therefore difficult to remember. In my case I always end up using the mouse instead of the shortcut.

AutoCode allows us define custom commands to invoke any IDE actions using a more intuitive shortcut.

An Example to Invoke “Close All But This”

For example, to close all the editor windows but the active one we need to move the mouse to the current document tab, right click the mouse and then click the “Close All But This” option. It would be faster just to invoke an AutoCode command like, for example, ‘ca’ for “Close All”. It is, Ctrl+Enter and then ‘ca’.

The following command does exactly that by invoking the “File.CloseAllButThis” IDE command.

<?xml version="1.0"?>
<Commands xmlns="http://schemas.devprojects.net/AutoCode/v3.0">
  <Command name="CloseAllButThis">
    <CommandBehavior>
      <CommandLine shortcut="ca" />
    </CommandBehavior>

    <CommandCode language="csharp">

      <Execute>
        DTE.ExecuteCommand("File.CloseAllButThis", "");
      </Execute>

    </CommandCode>
  </Command>
</Commands>

Using the <Execute> Tag to Execute Code

The <Execute> tag allows us to execute any script of code we want. In this case we are invoking the “File.CloseAllButThis” IDE command, but we can execute any other IDE command or furthermore, we can execute any piece of code.

In the example we are using csharp as the script language, but we can use also VB.BET like in the following example. Notice the language attribute (and also the missing semicolon at the end of the sentence :)

    <CommandCode language="vb">

      <Execute>
        DTE.ExecuteCommand("File.CloseAllButThis", "")
      </Execute>

    </CommandCode>

Other IDE Commands

Modifying this simple command, any of the IDE commands can be easily invoked from the AutoCode input box. Just replace the name, shortcut and command name.

Here are some examples of other useful IDE commands:

Edit.CommentSelection for commenting selected code
Edit.UncommentSelection for uncommenting selected code
View.TaskList to show the TaskList Window
Debug.Immediate to show the Immediate Window
Edit.FormatDocument to format the whole document

All IDE actions that have an associated command can be used. To know the exactly name of the IDE command you can use the Options menu:

1. Open the Tools->Options window
2. Select Environment->Keyboard
3. On the “Show commands containing” textbox write any word of the command and the list of commands containing that word will appear