citrix dev guide

7/29/2019 citrix dev guide

1/46

CitrixWorkflow Studio 1.1

CitrixWorkflow Studio Activity Developers Guide


2/46

Copyright and Trademark Notice

Use of the product documented in this guide is subject to your prior acceptance of the End User License Agreement.

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are

fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means,electronic or mechanical, for any purpose, without the express written permission of Citrix Systems, Inc.

2006-2009 Citrix Systems, Inc. All rights reserved.

Citrix, is a registered trademark of Citrix Systems, Inc. in the United States and other countries.

Trademark Acknowledgements

Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Adobe Systems Incorporated in the U.S. and/or

other countries.

Microsoft, Windows, Windows Media, Windows Server, Windows NT, Win32, Outlook, ActiveX, Active Directory, and

DirectShow are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks and registered trademarks are the property of their respective owners.

Document Code: February 17, 2009 (KP)
http://../CitrixInfocat.pdfhttp://../CitrixInfocat.pdf


3/46

CONTENTS

Contents

Chapter 1 Preparing for Activity Library Development

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Citrix Tools and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2PowerShell Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Standard Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Activity Library Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Installation and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Adding the Required Assembly References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Installing the Converter and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Next Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2 Converting PowerShel l Snap-ins to Activi ty Libraries

Creating a Project and Generating Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Editing the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

References to the Snap-in Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Input/Output Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Dependency Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Reviewing Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Testing the Activity in a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Add references to the snap-in binary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Change optional integer properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Use strong names for activity libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Add custom activity icons and reference them . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Determine if any overrides are needed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Review validation logic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Other Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3 Creat ing Activities from Cit rix Templates

Creating an Activity from a Citrix Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Editing the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Dependency Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Activity Execution Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Validation Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
http://../document_center.pdfhttp://../document_center.pdf


4/46

4 Workf low Studio Act ivi ty Developer s Guide

Testing the Standard Activity in a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 4 Activity Attribute Reference

General Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

PowerShell-Specific Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Dependency Property Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

PowerShell-Specific Property Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41


5/46

CHAPTER 1

Preparing for Activity Library Development

The following topics provide an overview to activity libraries and describe the

installation requirements:

Overview on page 1Citrix Tools and Templates on page 2

Activity Library Design Considerations on page 3

Installation and Setup on page 5

Next Steps on page 7

OverviewWorkflow Studio, a member of the Citrix Delivery Center product family, is an IT

process automation solution that is built on the Microsoft .NET Framework, Windows

Workflow Foundation, and Windows PowerShell. Citrix Workflow Studio includes a re-

hosted and extended version of the Workflow Foundation Designer that provides

additional functionality that simplifies the creation of workflows from activities.

An activity library is a collection of activities stored as a compiled binary (a .dll).

Workflow Studio includes some basic activity libraries, a defined way to extend

Microsoft's Workflow Foundation. Citrix is also developing activity libraries that

integrate products such as Citrix XenDesktop, XenApp, XenServer, and NetScaler to

enable your IT infrastructure to operate as a dynamic delivery platform.

Citrix partners are invited and encouraged to create custom activity libraries to take

advantage of the benefits of Citrix Workflow Studio. Building a custom activity library

for Workflow Studio is similar to building a Workflow Foundation activity library. In fact,

you can build a Workflow Foundation activity library and use it in Workflow Studio.

However, if you build an activity library as described in this guide, some of the

development work is done for you and a workflow developer using your library can

take advantage of the Workflow Studio extensions that simplify workflow development

and provide functionality targeted to IT administrators.

Your custom activity libraries might integrate with your own or third-party products (that

have PowerShell snap-ins) to provide functionality such as the following:
http://../document_center.pdf


6/46


Power Management

Being able to power on/off both physical and virtual servers automatically

provides the ability to better manage your resources and, ultimately, save oncosts by having your power-hungry servers off when they are not needed.

User Provisioning

Every organization has a process for provisioning and de-provisioning user

accounts, but often these processes involve multiple manual steps. Automating

the process end-to-end ensures that best practices are followed in exactly the

same way each time.

Dynamic Resource Allocation

Transform your data center into a delivery center by creating workflows that tie

together your server provisioning process (both physical and virtual) with your

web, desktop, and application delivery processes. Your custom activities and

workflows can mechanize repetitive configuration processes and coordinate

condition-based triggers for administrative tasks.

Disaster Recovery

Most disaster recovery teams have a binder that lists all the activities that must

take place in the face of different events. Automating all your failover scenarios

and recovery events is a perfect use case for Workflow Studio. You may not be

able to define all the different disasters that might happen but you can define all

the different responses. Even better, you can automate the responses and just

embed notifications for what the system is doing on your behalf.

Product Automation

A good place to start is with the little things that bother people. There are lots of

opportunities around individual products to offer additional value-add and plenty

of opportunity to automate around product quirks. Product automation also

ensures that a process implemented around best practices is always performed

the same way regardless of who runs the workflow. In addition, Workflow Studio

provides a way to react to problems with software deployments automaticallyand resolve them without the need for user interaction.

Citrix Tools and TemplatesWorkflow Studio is built on Workflow Foundation and shares the same underlying

architecture. The same activity libraries that you build for Workflow Foundation can be

used within Workflow Studio. This means that you can access all the resources

Microsoft has available and reference their samples.

Workflow Studio extends on Workflow Foundation; some of the functionality in our

Designer requires you to code your activity library to target our platform. We have

developed some templates for Visual Studio that allow you to easily build activity

libraries to target Workflow Studio.


7/46

Chapter 1 Preparing for Act ivi ty Library Development 3

PowerShell ConverterIf you have a PowerShell snap-in that you would like to use in Workflow Studio as anactivity library, the Citrix PowerShell Converter (a wizard and templates) help automate

the process. The Converter wizard inspects the snap-in and lists all of the cmdlets

available. After you select the cmdlets you want to use, the wizard generates a project

with one activity per cmdlet.

The wizard automates much of the activity development process: It sets up all of the

references, and adds one class file for each cmdlet selected from the PowerShell

snap-in. This automated process also does a reasonable job of inspecting the cmdlet

parameters and converting them, but you will want to look through the parameters and

the validation logic before you deploy the activities.

Standard Templates

If you want to build an activity library that targets Workflow Studio and does not usePowerShell, our basic Activity Library Project and Item templates help you get started.

They set up the necessary project references and generate sample code that is

heavily commented with the various parameter and validation options.

Activity Library Design ConsiderationsThe core activities in Workflow Studio include support for running PowerShell

commands/scripts and VBScript. While this functionality allows access to many

existing Citrix APIs today, it is not an ideal solution for your customer. Accessing APIs

in this manner does not expose the rich functionality available in the workflow model.

For instance, when you have a script output data, other activities cannot know what

data types are output and often cannot bind to individual properties on objects as a

result.

The best experience is to develop a native activity library and provide first-class

access. The activity libraries that are included with Workflow Studio and the extensions

for Windows, Active Directory, and Group Policy support provide good examples of the

best way to implement an activity library.

To build an activity library from a PowerShell snap-in, you must understand the snap-in

to achieve the intended design goals. Considerations for designing activity libraries are

as follows.

Consider what is the best architecture for the activity library.

Ultimately, the best architecture to use when creating an activity library depends

on the APIs that are available for the product you want to access and the skill

set of the development team. Because Workflow Studio natively supports

PowerShell cmdlets, if a PowerShell library is available for the product you wantto integrate with AND that library closely matches the types of activities you

would like to expose, using the converter is best. However, any technology that

can be accessed from .NET can be used in an activity, so it is not necessary to

create a PowerShell library solely for the purpose of translating to an activity

library.


8/46


Consider what is needed (and not needed) for automation .

Try to identify the most likely automation scenarios (perhaps the top ten) and

design around those scenarios. Consider the types of functionality your

customer wants to automate and ensure that you are providing the necessary

tools.

A workflow developer will use your activity libraries, plus other activity libraries,

when building a workflow. Take care in naming the activities so that their

purpose is obvious, even to a non-developer. And, make sure that the links

between the activities needed to accomplish automation are fairly easy to bind

together.

Keep in mind that activity libraries are used by workflows.

Ultimately, the design of your activity library will impact the IT administrators who

run workflows that use your library. Thus, you need to think in terms of

workflows. For example, suppose that you are developing activities related to

server maintenance. A common task in working with servers is enteringcredentials. An administrator should not have to enter server credentials

repeatedly to use a workflow. Your activities should be designed so that

workflows based on them enable administrators to run the workflow without

intervention.

What seems to make the most sense to the IT administrator is an architecture

that is object-based and provides verbs that operate on those objects. For

example, Get-VM retrieves a VM object and Stop-VM requires a VM object to be

passed to it.

Consider the optimum scope of activities and activity libraries.

An optimum design maintains a balance between too many specific activities

versus too few general activities. When you convert a PowerShell snap-in to an

activity library, the converter creates one activity for each selected cmdlet.

Depending on the design of the snap-in and your target workflows, you mightneed to combine several commands into one activity or even separate a

generated activity into multiple activities.

For example, if the conversion of a PowerShell snap-in results in an activity that

is too general and has many properties, you might find it better to make the

activity more specific by specifying some of the properties. Suppose that the

conversion resulted in an activity called Add that takes a property of the object to

be added. You could edit that activity to be more specific (AddItem), prefill some

of the properties, and then hide those properties so they do not appear in the

Workflow Studio window.

Often the APIs that exist for a product are not designed in an optimal way to be

used in a workflow. For example, you need to think about the API functions and

objects that are typically only used during initial setup or rarely in the life of the

product. Related activities would be good candidates to hide by default (inWorkflow Studio), put into a separate library, or omit.


9/46


Installation and SetupUse of the Citrix templates for activity development requires the following to be

installed on your development computer:

Microsoft Visual Studio 2008 Professional, Team, or Standard editions

(the Express edition does not support Workflow Foundation)

Microsoft .NET Framework 3.5

Windows PowerShell 1.0

Citrix Workflow Studio Release 1.0 or later

Alternatively, you can copy a few dlls from a Citrix Workflow Studio installation to

your development computer so that Visual Studio has the required assembly

references, as described in Adding the Required Assembly References on

page 5.

The Citrix templates

Install the Citrix templates as described in Installing the Converter and

Templates on page 6.

Adding the Required Assembly References

Note If you choose to install Citrix Workflow Studio on your development computer,you can skip this topic. The Workflow Studio installer and installation instructions

are available from http://www.citrix.com/wfsinsider. You must log in to MyCitrix

to access the Workflow Studio download.

If you choose to not install Citrix Workflow Studio on your development computer, youmust copy five files from a computer where Workflow Studio is installed to your

development computer and add them as references to Visual Studio. The five files are

components from Workflow Studio that are referenced from within the activity libraries

that you create using the Citrix converter or templates.

1. On the computer where Workflow Studio is installed, open a Command Prompt.

Copy each of the following files to your development computer:

C:\WINDOWS\assembly\GAC_MSIL\Common\1.0.0.0__78e03b5295a4e20d\Common.dll

C:\WINDOWS\assembly\GAC_MSIL\CustomActivityDesigners\1.0.0.0__8a86f49e1eb569bb\

CustomActivityDesigners.dll

C:\WINDOWS\assembly\GAC_MSIL\CustomActivityPropertyEditors\1.0.0.0__36841176f080fbec

\CustomActivityPropertyEditors.dll

C:\WINDOWS\assembly\GAC_MSIL\CustomActivitySerializers\1.0.0.0__1870553f17856880\

CustomActivitySerializers.dll

C:\WINDOWS\assembly\GAC_MSIL\User\1.0.0.0__35f94bb8b52992a3\User.dll

The location of those files does not matter. You will browse to them from the

Visual Studio Add Reference dialog box.


10/46


2. In Visual Studio open the Add Reference dialog box and click Browse to locate

and add the dlls listed in the previous step.

Installing the Converter and TemplatesThe Citrix Workflow Studio Developer Network website includes links to an installer for

the Citrix PowerShell Converter and an installer for the Citrix templates for Visual

Studio. Download and install those components as follows.

1. Navigate to http://community.citrix.com/cdn/. Mouse over Workflow Studio in

the top menu bar and choose Download SDKs.

2. Copy WFSTemplates.msi to your development computer.

3. To start the installation, double-click WFSTemplates.msi.

The installer first copies the Citrix PowerShell Converter DLL into the Global

Assembly Cache (GAC). It then creates a folder, c:\Program

Files\Citrix\Workflow Studio Templates, with one file, WFSTemplates.vsi. Theinstaller then runs the VSI file.

By default all Project and Item templates are selected for installation. The

Project templates add required references to the activities you create from the

Item templates.

Template installer

4. Click Next and then Finish.

The links that appear allow you to view the path to the installed files.


11/46


Last page of template installer

Note To uninstall the DLL and templates:1. Run Add/Remove Programs and then remove Citrix Workflow Studio

Templates.

2. Delete the templates from your Visual Studio Templates directories

in Documents and Settings:

ItemTemplates\Visual C#\Citrix Workflow Studio\

ProjectTemplates\Visual C#\Citrix Workflow Studio\

Next StepsThe following topics describe how to create activity libraries from the Citrix-provided

templates:

Converting PowerShell Snap-ins to Activity Libraries on page 9

Creating Activities from Citrix Templates on page 29


12/46



13/46

CHAPTER 2

Converting PowerShell Snap-ins toActivity Libraries

This tutorial covers the tasks related to developing an activity library from a PowerShellsnap-in by using the Citrix PowerShell Converter. In this tutorial you will perform the

following tasks:

Create an activity library project from a PowerShell snap-in.

Edit the generated code to add and change references, activity attributes, input/

output base classes, and dependency properties.

Review the project properties and change as needed.

Add the new activity to Workflow Studio and use it to create a workflow.

Understand the requirements for debugging validation logic versus debugging

execution logic.

Learn best practices for developing activities from PowerShell snap-ins.

This chapter covers the following topics:

Creating a Project and Generating Activities on page 10

Editing the Code on page 14

Reviewing Project Properties on page 19

Testing the Activity in a Workflow on page 20

Best Practices on page 23


14/46

10 Workflow Studio Activi ty Developer s Guide

Creating a Project and Generating Activities

Note The Citrix-provided documentation for Workflow Studio does not go into detailabout Microsoft technologies and products such as PowerShell, Visual Studio,

and the other technologies used as a foundation for Citrix Workflow Studio.

Many resources for those and other topics, such as workflow and activity

development, are available from the Microsoft MSDN online library and from

other Microsoft and third-party vendor sources.

The procedures in this topic assume that you have installed the Citrix templates, as

described in Installing the Converter and Templates on page 6.

To start, you will create an activity library project in Visual Studio and then use the built-

in Citrix PowerShell Converter to convert a PowerShell cmdlet to an activity. The

cmdlet that you will convert is the native Get-Date cmdlet, which returns the currentdate and time.

To create an activity library project and convert an activity

1. From the Visual Studio window, choose File > New > Project.

The New Project dialog box displays a list of project types and templates.

2. In the Project Types list, select Citrix Workflow Studio.

The Templates list shows the templates that you installed for Workflow Studio.l

3. In the Templates list, select PowerShell Activity Library.

The PowerShell Activity Library projecttemplate is not like the other templates in

that double-clicking it opens the Citrix PowerShell Converter rather than creating

an activity from the template. The converter enables you to select thePowerShell cmdlets for which you want to generate activities.

You can use the PowerShell Activity Library itemtemplate to add activities to

projects created by any Citrix project template.

4. Change the Name to GetDate and then click OK.


15/46

Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 11

New Project dialog box

5. The PowerShell Converter appears. In the converter, click the top drop-down list

to see all of the PowerShell snap-ins registered on your computer.

List of PowerShell snap-ins in the PowerShell Converter


16/46


6. Select the snap-in named Microsoft.PowerShell.Utility and then click the List

Cmdlets button.

A list of the cmdlets in that PowerShell snap-in appears.

Note Notice the Refresh button across from the List Cmdlets button. If you install anew PowerShell snap-in while the converter is open, you can click Refresh to

reload the list.

7. Select the cmdlets that you want to include in the project. For this tutorial, select

only Get-Date.

Get-Date cmdlet selected in the converter

8. Notice the Tree Path, which is where in the Workflow Studio Designer activity

tree that your custom activity will appear. Tree Path defaults to the Windows

Powershell folder (which appears under the root of the Workflow Studio

Designer activity tree). Change the Tree Path to Windows PowerShell/Utilities.

When you add your custom activity to Workflow Studio Designer, it will be

located in the Workflow Studio activity tree under Windows PowerShell >

Utilities.

9. To replicate the selected cmdlet in a new project, click Generate Project.

Visual Studio builds a Visual Studio project, sets up all of the references, and

sets the build destination. It also adds one class file for each cmdlet selected

from the PowerShell snap-in.

10. Click OK when the message Generation of project GetDate completed

appears.


17/46


11. To view the generated code: Right-click GetDate.cs in the Solution Explorer and

choose View Code.

12. Notice the using statements in the code.

Generated code in the GetDate.cs file

Included are references to the following Workflow Studio components.

Those components are also included in the References list in the Visual Studio

Solution Explorer.

Component Provides

Common Built-in validation routines. Base logic for the Workflow Studio password property. Customized ForEach, IfElse, and While constructs. Support for dynamically loading PowerShell snap-ins without needing to

use Add-PSSnap-in.

CustomActivityDesigner Support for the customized theme in the Workflow Studio Designer.

CustomActivityPropertyEditor Custom file browser, folder browser, text editor, and custom bindingdialog support.

CustomActivitySerializers Helper objects to make PowerShell serializable.

User Base classes you can derive from when building activities to simplify

access to PowerShell and WMI. Native tools to support development of UI activities.


18/46


If those references are missing from the generated code, you must either install

Workflow Studio on your development computer or install the required dlls as

described in Adding the Required Assembly References on page 5.

Editing the CodeWhile the Citrix PowerShell Converter automates much of the activity development

process, a developer must tune the overall design of the activity library and edit the

code to optimize use of the activities in a workflow. The comments in the generated

code guide you through the editing.

The following topics lead you through changes to the generated code:

References to the Snap-in Binary on page 14

Activity Attributes on page 15

Input/Output Base Classes on page 17

Dependency Properties on page 18

Note Code regions not covered in this tutorial typically do not need modification. Foradditional help, refer to the samples and comments in the generated code as

well as Best Practices on page 23.

References to the Snap-in BinaryThe Error List in the Visual Studio window has two messages related to a missing

assembly reference. After you convert a PowerShell snap-in to an activity, you must

edit the code to reference the snap-in binary: You must add a reference to the binary, ausing statement, and an ActivityReferenceAssemblies attribute.

To add references to the snap-in binary

1. To add a reference to the binary:

a. Choose Project > Add Reference.

b. Click the Browse tab and navigate to:

C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\

Microsoft.PowerShell.Commands.Utility.dll

Note: When you do not know which dll to reference, refer to the developer

documentation for the snap-in.

c. Click OK.

The References list now includes an entry for the added object.


19/46


2. Add the following using statement:

using Microsoft.PowerShell.Commands;

Note: The reference and the using statement names might not match. Refer to

the developer documentation for the snap-in if you need help.

3. To set up the ActivityReferenceAssemblies attribute on the project:

a. Open the Attribute Definitions and Comments region and copy the

following commented line to the end of the attribute definitions:

// [ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility,

Version=1.0.0.0, Culture=neutral, PublicKeyToken=12345ABCD6789EFG" } )]

You will need to replace the fully specified assembly name (everything

inside of the double-quotes) with the information for the added assembly.

A PowerShell command provides access to that information, as follows.

b. Uncomment the line, open a PowerShell window, and run the following

PowerShell command:[appdomain]::currentdomain.getassemblies() | sort -property fullname | format-table fullname

A list of assembly names appears.

c. From that list, copy the entire line that starts with

Microsoft.PowerShell.Commands.Utility and paste it in your code

between the double-quotes. The attribute will now look similar to the

following:

[ActivityReferenceAssemblies(newstring[] { "Microsoft.PowerShell.Commands.Utility,

Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" })]

Activity AttributesThe Attribute Definitions region contains the following generated code. These

attributes define characteristics of the activity when it is used in Workflow Studio

Designer.

[Designer(typeof(BaseActivityDesigner))]

[DisplayNameAttribute("Get-Date")]

[Description(@"Gets the current date and time.")]

[ActivityTreePath(@"Windows PowerShell/Utilities")]

[ActivityValidator(typeof(GetDateValidator))]

[ToolboxBitmapAttribute(typeof(GetDate), @"Resources.GetDate16.png")]

[BaseActivityDesigner(ImageResourceName = @"Resources.GetDate32.png", AssemblyType =

typeof(GetDate))]

[CTXPSCmdletInfoAttribute("Get-Date","Microsoft.PowerShell.Utility")]

[ActivityReferenceAssemblies(newstring[] { "Microsoft.PowerShell.Commands.Utility,

Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" })]


20/46


A summary of those activity attributes, described in detail in General Activity

Attributes on page 35 and PowerShell-Specific Activity Attributes on page 38,

follows.

Designer

Defines the activity designer to be used for the activity. The

BaseActivityDesigner is the Citrix designer that determines the appearance of

the activity in Workflow Studio Designer.

DisplayNameAttribute

The name that appears for the activity in the Workflow Studio Designer.

Description

Help text that appears in the Workflow Studio Designer under the Activity list

when this activity is selected.

ActivityTreePath

Specifies where the activity appears in the Activity list in Workflow Studio

Designer.

ActivityValidator

Defines the class responsible for the activitys validation logic. That validator

class appears at the end of generated code.

ToolBoxBitmapAttribute

Specifies the icon used for the activity in the Activity list.

BaseActivityDesigner

Defines several attributes that affect the appearance of the activity bubble on

the Workflow Studio design surface.

CTXPSCmdletInfoAttribute

Specifies the PowerShell cmdlet to run for this activity. This one line of code is a

good example of the work done for you when you convert a PowerShell cmdlet

to an activity. If you were to start from the base template to develop the activityfrom scratch, you would need about 30 lines of code to set up a connection to

PowerShell, load the runspace, load the snap-in, and call the cmdlet.

There are no other changes that you need to make to the attributes for this tutorial. You

generally will only need to change the two icon filenames and add/edit the

ActivityReferenceAssemblies line.

Be aware that the following attributes, not added by the template, are also available.

You can copy them from the comment block. They are also detailed in General

Activity Attributes on page 35 and PowerShell-Specific Activity Attributes on page

38.

ActivityReferenceAssemblies

Specifies other assemblies to be referenced by a workflow using this activity.

(You added this attribute earlier in this tutorial.)

BindTypesOverride

Allows you to specify additional data types to which the Input or Output

properties can be bound.

CTXPSParameterInfo

Maps activity properties to PowerShell parameters.


21/46


DesignerSerializer

Calls the Citrix BindingListSerializer. This attribute is required if your activity

includes bindable properties.

HiddenPSSnap-in

Specifies a PowerShell snap-in to be dynamically loaded at runtime.

Input/Output Base ClassesThe input/output base classes enable you to hide or modify input and output

properties. The GetDate activity created in this tutorial will simply return the current

date and time, so it does not need user input properties. You prevent the GetDate input

property from appearing in the Workflow Studio Designer Properties pane as follows.

To hide the input property

1. In the Input/Output Base Classes region, select the following lines and then

uncomment them.

//[Description("")]

//[Category("Parameters")]

//[Browsable(true)]

//[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]

//public override Object Input

//{

// get { return base.Input; }

// set { base.Input = value; }

2. Delete the Description and Category attributes. They are not needed for a

hidden input property.

3. Change the Browsable attribute to false so that the Input property for GetDate

will not appear in the properties list.

The input base class should now contain the following lines:

[Browsable(false)]

[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]

publicoverrideObject Input

{

get { returnbase.Input; }

set { base.Input = value; }

}


22/46


Dependency PropertiesA dependency property is a property to which other activities can bind. They are theproperties used by the cmdlet that you converted. When this activity is added to

Workflow Studio, the dependency properties will appear in the right pane of the

designer window (under Parameters) when you select the GetDate activity.

The GetDate activity you are creating does not need bindable properties, so you will

remove most of them.

To edit the dependency properties

In the dependency properties region, remove all properties exceptforFormat.

No other changes to dependency properties are needed for this exercise.

If you want to change the format of the output date/time, refer to the code

comments for the Format property.

A summary of the Format dependency property attributes follows. All attributes are

described in detail in Dependency Property Attributes on page 39.

Note Dependency property requirements are described in Best Practices on page23.

DisplayName

Specifies the name to appear for the property in the property grid.

Description

Contains the help text that appears below the property grid when the property is

selected.

CategoryDetermines under which group in the property grid the property will appear.

Browsable

Specifies whether the property will appear in the property grid or in the MS

binding dialog box.

DesignerSerializationVisibility

Specifies which part of a property should be serialized by the Workflow Studio

Designer.

EditorAttribute

Specifies which property editors, if any, are associated with this property.

CTXPSParameterInfo

Allows you to map activity properties to PowerShell parameters.


23/46


Reviewing Project PropertiesBefore you compile your work into a dll, review the project properties. Project

properties control items such as the output file destination and dll signing.

To review the project properties

1. In Visual Studio, choose Project> GetDate Properties.

Project Properties window for GetDate activity library

2. To change the output path, click Build.

The default is projectFolder/bin. Change the path if you want.

3. Click Signing. Notice that the Sign the assembly checkbox is selected and that

there is a default key file sn.snk. That placeholder key file is not password-

protected. This tutorial assumes that there is no password on the key file.

Note For activities that you plan to release publicly, you should replace the key filewith your own.

4. If you change any properties, right-click the GetDate tab and choose SaveSelected Items.


24/46


Right-click menu from the GetDate tab

5. Close the tab containing the project properties.

Testing the Activity in a WorkflowYou have now completed the custom activity and will now compile and test your edited

code.

To compile the code

In Visual Studio, choose Build > Build Solution.

The dll will be saved to the output path specified in the project properties (see

Reviewing Project Properties on page 19 for more information).

To test the activity in Workflow Studio

1. If you do not have Citrix Workflow Studio installed on your development

computer, copy GetDate.dll to the computer where Workflow Studio is installed,

into Program Files\Citrix\Workflow Studio.

2. Start Workflow Studio and create a workflow that will include the GetDate

activity:

a. Click the Workflow Studio Workflows tab and then click a workflow

category. (If no categories exist, you must create one.)

b. In the Actions pane, click Create Workflow.

c. Give the workflow a name and then click OK.

d. When the Workflow Studio Designer opens, notice that the Activities tabdoes not yet include a Utilities folder (under Windows PowerShell) where

the GetDate activity will be located. To see the new activity, you must

install the GetDate activity library and add the new activity to the Activities

tab, as follows.


25/46


3. To install the activity library in Workflow Studio:

a. Choose Tools > Choose Activities.

b. Click Browse,navigate to Program Files\Citrix\Workflow Studio, select

GetDate.dll, and click Open.

4. To add the GetDate activity to the Activities tab:

In the Choose Activities dialog box, select the checkbox of the GetDate

activity, and then click OK.

5. Add the following two activities to the workflow:

a. In the Activities tab, open the Windows PowerShell > Utilities folder. It

contains one activity, GetDate. Drag GetDate to the design surface.

b. In the Activities tab, open the Workflow Control > Debugging folder and

drag MessageBox to the design surface under GetDate.

Your workflow should look like the following screen sample:

Sample workflow using the custom GetDate activity

6. Now you will bind the output of the GetDate activity to the message text:

a. Select the messageBox activity in the workflow.

b. In the Properties pane to the right of the design surface, click Message

Text and then click the icon to open the Edit Message Text dialog box.

c. Type this text, followed by a space:

The current Date/Time is:

d. To add the output of the GetDate activity to that text, select Output (under

the getDate1 activities) and then click Add.


26/46


Edit Message Text Property dialog box

7. Click OK. To test the workflow, click Start.

The message box appears.

Output of the GetDate activity displayed in message boxYou have now completed this tutorial. The rest of this chapter contains information that

will help you in creating activities from PowerShell snap-ins.


27/46


Best PracticesBest practices for creating an activity from a PowerShell snap-in follow.

Add references to the snap-in binaryAn activity library project must reference the snap-in binary you are converting. You

must add the reference to the project, add a using statement, and add an

ActivityReferenceAssemblies attribute. For task details, see References to the Snap-

in Binary on page 14.

Change optional integer propertiesThe dependency property code is generated from the PowerShell snap-in. Review all

dependency properties for optional integer properties and change them as follows:

You must modify all optional integer properties (which control how the object is

displayed in Workflow Studio Designer) to be String properties. However, keep

the CTXAttributeType (which controls how we send the object to PowerShell)

set to Int32.

Thus, data from the user is obtained as a string; Workflow Studio then converts

the data to an integer before it is passed to PowerShell. As a result of those

changes you can bind these parameters to any other string parameter or

variable that might contain a number.

Suppose that when you were creating the GetDate activity, you retained the

dependency properties (which include Date, Year, Month, Day, Hour properties).

Because integers cannot be null and default to zero, leaving them as integers

causes zero to be sent for all the integer properties. Thus, those properties need

to be strings.

Note Although the core of Workflow Foundation is very strict about data types,Workflow Studio extensions reduce what you need to know about data types

and conversion.

Uncomment the EditorAttribute, which is used for strings.

Search for properties with

CTXPSParameterInfoAttribute.CTXAttributeType.Unknown and replace

Unknown with a type that makes sense for the object (most likely it will be

Object). The Unknown type is specifically included to throw a runtime error and

remind you to look at it.

Include additional design time and run time validation based on the integerrange expected to ensure that the entry is a valid integer in the correct range.


28/46


In the following code sample, the property changes just described are circled.

Use strong names for activity librariesWorkflow Studio requires that an activity library is internally signed (that is, has a

strong name), as covered in Reviewing Project Properties on page 19.

Add custom activity icons and reference themWorkflow Studio includes default icons that display for the activity in the Activities list

and in the activity bubble. Those icons are circled in the following screen sample:

Default images for ToolboxBitmapAttribute and BaseActivityDesigner

#region Year Propertypublic staticDependencyProperty YearProperty = DependencyProperty.Register("Year",

typeof(String), typeof(GetDate));

[DisplayName("Year")]

[Description("Specifies the year that is displayed. Enter a value from 1 - 9999. This value

is displayed instead of the current year.")]

[Category("Parameters")]

[Browsable(true)]

[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]

[EditorAttribute(typeof(TextEditor), typeof(UITypeEditor))]

[CTXPSParameterInfo("Year", AttributeType =

CTXPSParameterInfoAttribute.CTXAttributeType.Int32)]

//[BindTypes(new Type[] { typeof(Int32)} )]publicString Year

{

get

{

return ((String)(base.GetValue(GetDate.YearProperty)));

}

set

{

base.SetValue(GetDate.YearProperty, value);

}

}


29/46


You can replace those icons with your own.

To add and reference icons

1. Make sure that your icons are PNG files and are 16 pixels square (icon for the

Activities list) and 32 pixels square (icon for the activity bubble).

2. Add the icons as resources:

a. In the Visual Studio, select the project GetDate in the Solution Explorer

and choose Project > GetDate Properties. Click the Resources tab.

3. From the Resources tab, you can create a resources file and add the images to

it.

4. In the generated code, update the filenames in the following lines:

[ToolboxBitmapAttribute(typeof(GetDate), @"Resources.GetDate16.png")]

[BaseActivityDesigner(ImageResourceName = @"Resources.GetDate32.png", AssemblyType =

typeof(GetDate))]

The default images are provided as part of the base Workflow Foundation. You

will not find those images in the Workflow Studio application folders.

Determine if any overrides are neededThe Activity Execution Logic region of the code contains samples for common

overrides.

ExtraParameterValidation is used to perform a runtime validation of required

properties. When an exception is thrown, a message is displayed in Workflow

Studio Designer.

AddParameters is used to add parameters to the input objects. For the GetDate

example, if the dependency property Date was included in the user input, you

could add a parameter that would cause the date to be passed to PowerShell

only if it was set by the user. Heres a code sample for that:

protectedoverridevoid AddParameters(Command cmd)

{

base.AddParameters(cmd);

//add the date only if supplied

if (this.Date.ToString().Length > 0)

{

cmd.Parameters.Add("Date", true);

}

}

Review validation logicThe last region of the generated code is the validation logic. The PowerShell Converter

generates validation code based on the properties marked as required in the

converted PowerShell cmdlets. While that gives you a starting point, you should review

the generated code and determine the changes needed for correct validation.


30/46


Consider the following:

What you want to validate and how you want to validate it is not readily auto-generated.

A string might need deeper inspection and validation. For example, you might

want to validate that the user input satisfies the requirements of a phone number

or a MAC address. Or you might want to check that an integer fits a particular

range.

When you add an activity to Workflow Studio Designer, the activity bubble

includes a red icon which the user clicks to see a list of required properties. You

can add warning messages in the validation logic.

If you need to add custom validation code, add it above the StopOnError region.

An activity must include the generated StopOnError validation code.

Typically, if a workflow encounters an error, you just want to catch the error,

ignore it, and continue the workflow. StopOnError allows you to easily do that,rather than adding and configuring error handlers. All you have to do is set the

StopOnError property (automatically added to every activity based on a Citrix

template) to False.

Although error handling is very complex in Workflow Foundation and Workflow

Studio, the Citrix StopOnError extensions greatly simplify it for you.

Other Considerations

Use the correct process when debugging customactivities

When you need to debug an activity that will be used in Workflow Studio, you shouldfollow the standard Microsoft debugging principles. The only thing specific to Workflow

Studio that you need to be aware of is the difference between debugging the validation

logic and debugging the execution logic.

You must attach Visual Studio to the correct Workflow Studio process, as follows.

To debug...Connect Visual Studio tothis process... Which is the...

Validation logic(which runs at designtime, such as when youspecify a property)

wfs.exe Workflow StudioDesigner process

Execution logic

(for a workflow run whenyou click Start in theWorkflow StudioDesigner)

WorkflowExpressRuntime.exe Process used to run

workflows from theDesigner

Execution logic(for a deployed workflowor job)

WorkflowRuntimeHostService.exe Service the WorkflowStudio uses to run jobs


31/46


Keep the Workflow Studio Library tidyAs you test and tune an activity, you might copy the activity DLL to Workflow Studioseveral times. Generally, all you need to do before copying the updated activity DLL is

to exit Workflow Studio. (Otherwise, you will get a message that the DLL is in use.)

However, if you change the key file for the activity DLL, you should remove that activity

from the Workflow Studio library before adding the updated version to avoid getting

multiple copies of the activity in the library.

To remove an activity from the library, you must remove the ToolBoxItem statement for

the activity from the following Workflow Studio configuration files:

WFS.Config

This setting applies to your computer and must be changed (along with

user.Config) if you are using the PowerShell snap-ins to install the activity you

created.

Documents and Settings\All Users\Application Data\Citrix\Workflow

Studio\WorkflowStudio\version\WFS.Config

user.Config

This user setting must be changed to update the list in the Workflow Studio

Choose Activities dialog box.

Documents and Settings\userName>\Local Settings\Application Data\Citrix\Workflow

Studio\WorkflowStudio\version \user.Config

Note You can also reset the activity library to its default, thus removing all activitiesthat you have added, by deleting those configuration files. However, your SQL

server domain name and any other configuration changes you made will be lost.


32/46


Control Workflow Studio activity namesWhen you drag an activity onto the Workflow Studio design surface, the name of thatactivity is determined by a value in a file that is generated when you create the activity.The file, activity.Designer.cs, contains this line in the Activity Designer generated code:

this.Name = Name;

The Name is generated from the PowerShell snap-in name by removing the hyphen

from the name (because hyphens are not supported in activity names in Workflow

Foundation). For example, if you create an activity from the Get-Date snap-in, the

generated name is as follows:

this.Name = GetDate;

If the generated name begins with an upper case letter (GetDate), the first time

you drag the GetDate activity to the Workflow Studio design surface, the activity

name will have a 1 appended (GetDate1). The number is incremented for

subsequent uses (GetDate2, GetDate3).

If the generated name begins with a lower case letter (getDate), the first time

you drag the GetDate activity to the Workflow Studio design surface, the activity

name will match the generated name (getDate). A number is appended for

subsequent uses (getDate1, getDate2).


33/46

CHAPTER 3

Creating Activities from Citrix Templates

This tutorial covers the tasks related to creating an activity by using the Citrix Standard

Activity template for Visual Studio. This tutorial assumes that you have completed the

tutorial in Converting PowerShell Snap-ins to Activity Libraries on page 9.

This chapter covers the following topics:

Creating an Activity from a Citrix Template on page 29

Editing the Code on page 31

Testing the Standard Activity in a Workflow on page 33

Creating an Activity from a Citrix Template

Note The Citrix-provided documentation for Workflow Studio does not go into detailabout Microsoft technologies and products such as PowerShell, Visual Studio,

and the other technologies used as a foundation for Citrix Workflow Studio.

Many resources for those and other topics, such as workflow and activity

development, are available from the Microsoft MSDN online library and from

other Microsoft and third-party vendor sources.

In this tutorial you create a project from the Activity Library template and add to that

project an activity from the Workflow Studio Standard Activity template. Projects

created from the Standard Activity template are the same as projects created from the

PowerShell Converter. You can use the Citrix PowerShell Activity or Citrix Standard

Activity templates to add an item to either project type.

In this tutorial, you will create an activity that delays the processing of a workflow. (This

version of the delay activity is simpler to use.)

To create an activity library project from scratch1. From the Visual Studio window, choose File > New > Project.

The New Project dialog box displays a list of project types and templates.

2. In the Project Types list, select Citrix Workflow Studio.

The Templates list shows the templates that you installed for Workflow Studio.l

3. In the Templates list, select Activity Library.

4. Change the Name to AdvancedDelay and then click OK.


34/46


New Project dialog box

A blank project opens in Visual Studio.

To add an activity to the project

1. Choose Project >Add New Item.

2. In the Add New Item dialog box, select Citrix Workflow Studio, select Standard

Activity, enter the name AdvancedDelay.cs, and click Add.

Add New Item dialog box


35/46

Chapter 3 Creat ing Act iv it ies from Citr ix Templates 31

3. To view the code: Select AdvancedDelay.cs in the Solution Explorer and

choose View > Code.

Editing the CodeThe following tasks cover typical changes needed when creating an activity from the

Citrix Standard Activity template. If you need background information or more details,

refer to Converting PowerShell Snap-ins to Activity Libraries on page 9 and Activity

Attribute Reference on page 35.

Activity AttributesThe Attribute Definitions region contains the following generated code. You will change

the activity description and its location in the Workflow Studio Designer activity tree.

[Designer(typeof(BaseActivityDesigner))]

[DisplayNameAttribute(@"AdvancedDelay")]

[Description(@"This activity will .")]

[ActivityTreePath(@"Folder/SubFolder")]

[ActivityValidator(typeof(AdvancedDelayValidator))]

[ToolboxBitmapAttribute(typeof(AdvancedDelay), @"Resources.AdvancedDelay16.png")]

[BaseActivityDesigner(ImageResourceName = @"Resources.AdvancedDelay32.png", AssemblyType =

typeof(AdvancedDelay))]

To specify the activity attributes

1. Change the Description to:

[Description(@"This activity will delay for a specified amount

of time.")]

2. Change the ActivityTreePath to:

[ActivityTreePath(@"Windows PowerShell/Utilities")]

Constructor

To define the default value for the delay activity

1. In the Constructor region, uncomment the line:

\\this.IntegerProp = 0;

2. Change that line to:this.DelayTimeProp = 0;

Dependency PropertiesYou will uncomment a sample dependency property and edit it to correctly reference

DelayTimeProp.


36/46


To correct the dependency properties

1. Under Dependency Properties in the Sample Integer Property region,

uncomment the following code lines:

//public static DependencyProperty IntegerPropProperty =

DependencyProperty.Register("IntegerProp", typeof(Int32), typeof(AdvancedDelay));

//[DefaultValue("0")]

//[Category(@"Parameters")]

//[DisplayName(@"DependencyIntegerProperty")]

//[Description(@"Description.")]

//[Browsable(true)]

//[InputAttribute]

//public Int32 IntegerProp

//{

// get

// {

// return ((Int32)(base.GetValue(IntegerPropProperty)));

// }

// set

// {

// base.SetValue(IntegerPropProperty, value);

// }

//}

2. In the first l ine, change:

IntegerPropProperty to DelayTimePropProperty

IntegerProp to DelayTimeProp

That code line should look like this:

public static DependencyProperty DelayTimePropProperty =

DependencyProperty.Register("DelayTimeProp", typeof(Int32), typeof(AdvancedDelay));

3. Change the DisplayName value to DelayTime.

4. Change the Description value to Specifies the amount of time to

delay (in ms).

5. Change public Int32 IntegerProp to public Int32 DelayTimeProp

6. Change return ((Int32)(base.GetValue(IntegerPropProperty) to

return ((Int32)(base.GetValue(DelayTimePropProperty)

7. Change base.SetValue(IntegerPropProperty, value); to

base.SetValue(DelayTimePropProperty, value);


37/46

Chapter 3 Creat ing Act iv it ies from Citr ix Templates 33

Activity Execution LogicYou generally should include more specific exception handling. By default, WorkflowStudio just catches an exeception and rethrows it.

To add to the exception handling

In the Activity Execution Logic, under // Place your code here, add the

following to the try-catch block:

System.Threading.Thread.Sleep(this.DelayTimeProp);

Note Just above the try-catch block is an ExpandStringProperties method, whichautomatically expands all the string properties and, at run time, replaces the

actual values and returns the full string. Without that line of code, strings will not

be expanded.

Validation LogicYou will uncomment sample property validation and edit it to correctly reference

DelayTimeProp.

1. Under Sample Property Validation, uncomment this line:

//if (!GlobalUtilities.Int32Validates(MyActivity.IntegerProp)

2. Change that line to:

if (!GlobalUtilities.Int32Validates(MyActivity.DelayTimeProp.ToString()))

3. Uncomment this line:

//errs.Add(new ValidationError(@"You must specify a value for the 'IntegerProp'property.", 101, false, @"IntegerProp"));

4. Change that line to:

errs.Add(newValidationError(@"You must specify a value for the 'DelayTimeProp'

property.", 101, false, @"DelayTimeProp"));

Testing the Standard Activity in a WorkflowFollow these general steps to test the AdvancedDelayActivity. For task help, refer to

Testing the Activity in a Workflow on page 20.

1. Build the activity in Visual Studio.

2. Add the activity to Workflow Studio.

3. In Workflow Studio, create a workflow and add the AdvancedDelay activity to it.

4. Change the DelayTime parameter to 5000.

5. Run the workflow.

You have now completed this tutorial.


38/46



39/46

CHAPTER 4

Activity Attribute Reference

The following topics describe the Workflow Studio activity attributes:

General Activity Attributes on page 35

PowerShell-Specific Activity Attributes on page 38

Dependency Property Attributes on page 39

PowerShell-Specific Property Attribute on page 41

General Activity AttributesThis topic describes the following general activity attributes:

Designer on page 35

DisplayNameAttribute on page 36

Description on page 36

ActivityTreePath on page 36ActivityValidator on page 36

BaseActivityDesigner on page 36

ToolboxBitmapAttribute on page 36

DesignerSerializer on page 37

ActivityReferenceAssemblies on page 37

BindTypesOverride on page 37

[Designer(typeof(BaseActivityDesigner))]Defines what activity designer will be used for the current activity. The

BaseActivityDesigner is the Citrix designer, which renders an activity as follows:

Appearance of an activity defined by BaseActivityDesigner

The glass look, background color, selected glow, font, icon position, and other

attributes are defined in BaseActivityDesigner.


40/46


[DisplayNameAttribute(@"name")]

Attribute allows you to specify the name for your activity. This is the name that willappear in the toolbox, and the same name that will appear on the activity in the design

surface when dropped there. Any spaces in this name will be replaced with underscore

characters when the activity is dropped on the design surface.

[Description(@"text")]Allows you to provide a brief text description of the activity. This text will appear at the

bottom of the toolbox in the Workflow Designer console when the activity is selected in

the toolbox. Typically, this text is short and simply gives a high-level overview of what

the task does.

[ActivityTreePath(@"path/name")]Allows you to specify where you want this activity to appear in the toolbox. This is

essentially the folder name. Note, use forward-slashes, not back-slashes, to separatefolders in the path, if you have nested folders.

[ActivityValidator(typeof(CreateVMValidator))]Defines which class is responsible for the validation logic of the activity. Typically each

activity has its own, dedicated validator class and, if the provided activity template is

used, will reside at the bottom of the activity .cs file.

[BaseActivityDesigner(ImageResourceName = @"name.png",AssemblyType = typeof(CreateVM))]Allows you to specify any one, or multiple, of the following attributes of the designer

itself:

The AssemblyType is also required.

[ToolboxBitmapAttribute(typeof(CreateVM), @"name.png")]

Allows you to specify the 16x16 image file to use as the icon for the activity in thetoolbox (tree view). The image must be a .png file. The image does not need to be the

exact same image as that supplied in the BaseActivityDesigner attribute, but usually is.

ImageResourceName(a 32x32 png icon/image)

TextForeColor

ShineColor ShapeRadius

GlowColor TextFontFamily

GlowIntensity TextFontSize

BackColor Width

MaskColor Height


41/46

Chapter 4 Act iv ity Att ribute Reference 37

[DesignerSerializer(typeof(BindingListSerializer),

typeof(WorkflowMarkupSerializer))]If you have any BindingList properties in this activity your activity needs to declare a

DesignerSerializer attribute calling the Citrix BindingListSerializer.

[ActivityReferenceAssemblies(new string[] { @"assembly"})]Allows you to specify one or more additional assemblies that must be referenced by

the workflow project. By default, if an activity references an assembly, that referenced

assembly will be added as a reference to the workflow project. However, sometimes

an assembly isnt referenced to an activity and therefore needs to be specified using

this attribute. This informs the Workflow Designer to manually add the specified

assembly as a reference to the workflow project.

The ActivityReferenceAssembliesAttribute takes one parameter which is a string that

is expected to be the full name of the assembly. For example:

[ActivityReferenceAssemblies(new string[] { @"XenDotNetLibrary, Version=1.0.0.0,

Culture=neutral, PublicKeyToken=3509c8c16f49bbe9" })]

In the process of handling this attribute to create a project reference, a call to

Assembly.ReflectionOnlyLoad() is made assuming that the string is the assembly

FullName. That ReflectionOnlyLoad() call is very forgiving in that it will accept just the

assembly name or the assembly name and version, etc. So, if you provide just the

assembly name like the following:

[ActivityReferenceAssemblies(new string[] {@"XenDotNetLibrary"})]

It will work just fine. Just be aware that if the activity which is decorated by the above

attribute (XenDotNetLibrary in this case) needs to reference a specific version of the

XenDotNetLibrary assembly in the future, then that string above will need the version

number added.

[BindTypesOverride("Input", new Type[] { typeof(String) })][BindTypesOverride("Output", new Type[] { typeof(String) })]Allows you to specify additional data types to which the Input or Output properties can

be bound.


42/46


PowerShell-Specific Activity AttributesThis topic describes the following PowerShell-specific activity attributes:

CTXPSCmdletInfoAttribute on page 38

CTXPSParameterInfo on page 38

HiddenPSSnapIn on page 38

[CTXPSCmdletInfoAttribute(@"cmdlet", @"snapIn")]Allows you to specify the Powershell cmdlet that an activity runs. This attribute is

applicable to activity classes that inherit from PSActivityBase.

PSActivityBase::Execute will execute the specified Powershell cmdlet, with the

parameters specified by the CTXPSParameterInfo attributes.

The first parameter is the cmdlet name. The second (optional) parameter is the snap-in

name. If a snap-in name is specified, that snap-in will be loaded in the runspace beforethe cmdlet is called).

[CTXPSParameterInfo("browserName", AttributeType =CTXPSParameterInfoAttribute.CTXAttributeType.NonEmptyString)]Allows you to map activity properties to Powershell parameters. This attribute should

be applied to properties (or dependency properties) of an activity class that inherits

from PSActivityBase. The common code in PSActivityBase adds the Powershell

cmdlet parameters, using the activity properties, as specified by this attribute. The first

parameter is the Powershell parameter name. The second parameter (AttributeType)

specifies how the value for that Powershell parameter should be handled (i.e. string,

PSObject, SwitchParameter, etc.)

[HiddenPSSnapIn("assemblyName")]Allows you to specify a Powershell snap-in to be dynamically loaded at runtime. This

allows you to use Powershell cmdlets that are not defined in a registered PSSnapin on

the computer. It takes one parameter, which is expected to be the full name of the

assembly. For example:

[HiddenPSSnapIn("XenAppCmdlets, Version=1.0.0.0, Culture=neutral,

PublicKeyToken=null" )]

The assembly is loaded, and any cmdlets within it are dynamically added to the

runspace. This attribute applies to activity classes that inherit from PSActivityBase.


43/46


Dependency Property AttributesThis topic describes the following dependency property attributes:

DefaultValue on page 39

Category on page 39

DisplayName on page 39

Description on page 39

Browsable on page 39

InputAttribute on page 40

OutputAttribute on page 40

EditorAttribute on page 40

ReadOnly on page 40

DesignerSerializationVisibility on page 40

BindTypes on page 41

ShowInWFSEditors on page 41

[DefaultValue(@"")]Allows you to specify a value that the property grid will identify as the default value. If

supplied, default values appear as normal text and when the value is changed from the

default the value appears as bold text.

Note: The actual default value for a dependency property must be set in the

constructor for the activity class. This attribute simply alters the behavior of the

property in the property grid.

[Category(@"Parameters")]Allows you to specify the group within the property grid where you want the property to

appear. The normal default for Workflow Studio activities is Parameters. Consider

placing parameters that are optional under a different category.

[DisplayName(@"Message Text")]Allows you to specify the name of the property as it will appear in the property grid (in

the left-hand column of the property grid).

[Description(@"Specify the text to display in the message box.")]Allows you to specify a text description of the property. This text description will appear

at the bottom of the property grid when the property is selected in the property grid.

[Browsable(true)]Allows you to specify whether the property will appear in the property grid. If omitted,

the property will be displayed. If supplied and the attribute value set to false, the

property will not be displayed.


44/46


[InputAttribute]

Allows you to specify whether the property is an input type of property. Using thisattribute simply puts an input icon next to the property in the binding drop-down.

Note: If this attribute is include, the OutputAttribute should not be included.

[OutputAttribute]Allows you to specify whether the property is an output type of property. Output

properties receive a special output icon next to the property in the binding drop-down,

and they will always appear in the TextEditor editor, regardless of their data type.

Note: If this attribute is included, the InputAttribute should not be included.

[EditorAttribute(typeof(TextEditor), typeof(UITypeEditor))]Allows you to specify which property editors, if any, are associated with this property.

Any editor can be used, but the following is a list of available editors included withWorkflow Studio:

[ReadOnly(true)]Allows you to specify whether the property value is allowed to change. Setting the

ReadOnly attribute value to true will restrict the value from being changed by the

user.

[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]System.ComponentModel.DesignerSerializationVisibilityAttribute specifies what part

of a property should be serialized by the designer. This attribute is usually necessary

when creating custom Web and Windows controls.This attribute takes one parameter, which is a

System.ComponentModel.DesignerSerializationVisibility enumeration member:

Visible

Specifies that the object should be serialized. Use this value for simple (or

primitive) properties.

BindingDropDownListEditor OpenFileEditor

DropDownList OpenFolderEditor

DSComputerPicker PasswordEditor

DSGroupPathPicker PropertyColumnEditor

DSObjectPathPicker StringEdit

DSOUPicker StringWithConstructor

EditorHelper TextEditor

FileWithConstructor TrusteeEditor

FolderWithConstructor VariableEditNamedCollectionEditor


45/46


Content

Specifies that contents of the object should be serialized. Use this value for

complex (or non-primitive) properties and collections.

Hidden

Specifies that the object should not be serialized. Use this value when

properties are changed for design-time purposes only, but should not be

serialized in code.

In Workflow Studio, this attribute is used for most properties to ensure proper

serialization during design time.

[BindTypes(new Type [] { typeof(String) } )]Allows you to specify alternate/additional property types that are allowed to bind to this

property. This is used in several activities but the best example is the Simple Math

activity. In that activity there are two input properties for the two input numbers that are

going to be used to perform a mathematic operation with. Some other activities mayoutput numbers that can/should be used by Simple Math in varying types Int32,

Int64, Float, Double, Decimal, Object, or even a String. Putting these types into the

BindTypes attribute allows the input properties of the Simple Math activity to be bound

to any property that is one of those types.

Note: Care must be taken to cast the input type appropriately so that exceptions are

not encountered when using the bound property values in the activity.

[ShowInWFSEditors]Allows you to override the Browsable attribute to cause properties to show up in the

TextEditor editor, even though they may be hidden in the property grid itself.

PowerShell-Specific Property Attribute[CTXPSParameterInfo(@"ServerName", AttributeType =CTXPSParameterInfoAttribute.CTXAttributeType.String)]Allows you to define identify a property as a parameter to the cmdlet. The first

parameter to this attribute is the cmdlet parameter name, the second is the cmdlet

parameter type. Valid parameter types are:

Boolean Long String

BoolString NonEmptyString StringList

Dictionary Object Switch

Enumeration Password UInt

Guid PSCredential UInt32

Int PSObject ULong

Int32 PSObjectArray Unknown

IntList


46/46
