Custom Code Snippets

Some scripts require more complexity than Studio actions alone can provide. Studio allows you to add custom code to your scripts. This allows you to customize your scripts to meet your organization's needs.

Custom coding requires some scripting or programming knowledge. Studio uses a custom programming language called Snippet, developed for use in Studio. A complete technical reference guide is available in the online help so you can learn to use this language.

Key Facts About Snippets

  • Code snippets can help improve the organization and efficiency of your scripts. They increase your control over the processes that execute, as well as when and how they execute. You can create your own variables and objects and add programming logic using statements such as IF, FOR, FOREACH, and others.
  • Some products and features require snippets, but you can use them in your scripts even when they're not required.
  • When a product or feature requires code snippets, the online help provides detailed information about the snippets you need to include. Examples of scripts are provided to show how to use the code snippets in scripts. Additional scripting may be required to implement the products or features.
  • The Snippet scripting language is built on the .NET framework. It executes server-side and compiles into MSIL (Microsoft Intermediate Language) just as C# and Visual Basic .NET do.

Snippet Action

To add custom code to your scripts, you need a Snippet action. You can double-click this action to open an editor window where you can add your custom code. You can also debug the code in the editor window. You may need more than one Snippet action in your script. If you use multiple actions, update the Caption field of each one with a phrase that helps identify its purpose.

Placement of a Snippet action matters. If a Snippet assigns a value to a variable, it must be placed before the action that needs the value. On the other hand, if a Snippet contains decision-making code that acts based on a value passed to it, the Snippet must be placed after the action that provides the value.

Snippets Compared to Actions

Some of what you can do in snippets can also be done using Studio actions. For example, there are actions for IF and FOR statements. There's also the ASSIGN action, which you can use to create a custom variable and assign it a value. Using these actions is an acceptable way to add these capabilities to your script. However, using snippets is more efficient.

By placing code in snippets, your script is cleaner, more organized, and easier to navigate. This makes your job as a scripter easier and more efficient. If you make it a habit to always declare variables in snippets, then in the future if you need to locate a particular declaration, you have fewer places to look.

Add Custom Code to a Script

The Snippet action allows you to add custom code to your scripts. This action is located in the Advanced section of the default palette on the Tools tab.

  1. In Studio, open your script.
  2. Place a Snippet action in your script wherever you need the code and connect it to the other actions.
  3. Double-click the action to open the editor window. This is where you can add your code.

  4. Click the tab you want to use to add your code. Each tab provides a different method of adding code. The tabs are:

  5. Debug your code, if you want to.

  6. Click Apply at any time to save your changes without closing the editor window.
  7. Click OK when you're finished editing the code.

Code with Text View

The Text View tab in the Snippet window allows you to write your Snippet code by hand. A complete reference guide is available in the online help so you can learn to use this language.

  1. In Studio, open your script.
  2. Add the Snippet action to your script and double-click on it to open the Snippet window.
  3. On the left side of the Tree View tab, enter your code. You can type the code in or copy and paste it from another source, such as this help site or another script.
  4. Click the Tree View tab at any time to add code from the predefined keywords. You can use the up and down arrow buttons to move code related to a keyword to a different spot in the script.
  5. Click the Check Syntax icon The Check Syntax icon, three small green circles with a triangle pointing to the right. to verify that your syntax for the current code is correct. The status field in the toolbar at the bottom of the Text View tab displays the status Okay if there are no errors. If there are errors, a pop-up message about the error appears and the status field in the toolbar displays a message. For example, the message might read Error at line 4.
  6. Click the Comment icon The Comment icon, an open angle bracket and a closed angle bracket with a blue forward slash in between them. to convert the line where the cursor currently sites into a comment.
  7. Click the Uncomment icon The Uncomment icon, a large red forward slash superimposed over an open angle bracket and a closed angle bracket with a forward slash between them. to remove the comment characters from the line where the cursor currently sits.
  8. Click Apply at any time to save your changes without closing the editor window.
  9. Click OK when you're finished editing the code.

Code with Tree View

The Tree View tab in the Snippet Properties window guides you through the process of creating custom code. A predefined set of keywords is available for you to choose from.

  1. In Studio, open your script.
  2. Add the Snippet action to your script and double-click on it to open the Snippet window.
  3. Click the plus icon A plus sign with an arrow next to it pointing down. at the bottom of the Tree View tab.

  4. The Snippet properties window, showing the Tree View tab. The green plus-sign icon is pressed and the menu of Snippet commands is visible.

    Select the keyword you want to add to your code.
  5. Click the keyword that appears in the list on the left side of the window to view its properties.

  6. Configure the keyword's properties in the list on the right side of the window. You can: 

    • Select each property to view a definition of the property in the space below the right pane.
    • Refer to the Snippet Keywords section on this page for details about configuring each command.
  7. Add more keywords as needed.
  8. Click the Text View tab at any time to view the code written out in traditional coding format.
  9. Click Apply at any time to save your changes without closing the editor window.
  10. Click OK when you're finished editing the code.

Debug Snippet Code

The Snippet action has its own debugger that you can use to check the code. You can only debug code from the Text View tab.

If you created your code on the Tree View tab, you can use the debugger if you switch to the Text View tab. If the debugger finds any issues, use the specified line number to determine which part of the code contains the issue. You can then return to the Tree View tab to correct the problem.

More debugging options are available, including stepping through the code line by line and using breakpoints. You can also use TRACE statements in snippet code to output text during debugging. This output can be useful when solving problems in your script.

  1. In Studio, open a script containing a Snippet action.
  2. Double-click on the Snippet action.
  3. Add Snippet code on the Text View tab, if it doesn't already contain some.
  4. On the right side of the Snippet editor window, click the Debugger tab.
  5. Click the down-arrow button on the right side of the Debug icon An icon of a window with a green right-facing triangle. On the right side of the icon is a down-facing black triangle that opens a drop-down menu. and select StartAn icon of a green play button triangle. .

  6. If there are any syntax errors in the code, the Snippet editor window expands. All errors in the code appear in a pane at the bottom of the window. If there are no errors, skip to the next step.

    The Snippet editor window, showing the errors pane at the bottom of the window.
    1. Correct the errors.
    2. When the errors have been corrected, click the Close or Clear Trace Output icons An X. to close the error pane.
    3. Start the debugger again.
  7. View the contents of the Variables as Text tab. The tab shows the variables and their values when all of the code has been executed if you didn't set a breakpoint.
  8. You can select one or more lines in the snippet code and click the Comment out selected lines icon An icon with open and closed angle brackets next to each other with a blue forward slash between them. . This is helpful if you want to remove some code to see how the outcome of the debugging changes.
  9. You can select one or more lines of commented-out code and click the Uncomment the selected lines icon An icon with open and closed angle brackets next to each other with a forward slash between them. A large red forward slash crosses the other characters. to add those lines back into the snippet.