Citrix Dev Guide

Citrix Workflow Studio Activity Developers Guide
Citrix Workflow Studio 1.1
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)
C ONTENTS
Contents
Chapter 1
Preparing for Activity Library Development

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Citrix Tools and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Library Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding the Required Assembly References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Converter and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 3 3 3 5 5 6 7
Chapter 2
Converting PowerShell Snap-ins to Activity Libraries

Creating a Project and Generating Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . References to the Snap-in Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input/Output Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependency Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reviewing Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Activity in a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Add references to the snap-in binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Change optional integer properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use strong names for activity libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Add custom activity icons and reference them . . . . . . . . . . . . . . . . . . . . . . . . . . Determine if any overrides are needed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Review validation logic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 14 14 15 17 18 19 20 23 23 23 24 24 25 25 26
Chapter 3
Creating Activities from Citrix Templates

Creating an Activity from a Citrix Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependency Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activity Execution Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 31 31 31 31 33 33
Workflow Studio Activity Developers Guide

Testing the Standard Activity in a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Chapter 4
Activity Attribute Reference

General Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell-Specific Activity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dependency Property Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PowerShell-Specific Property Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 38 39 41
C HAPTER 1
The following topics provide an overview to activity libraries and describe the installation requirements: Overview on page 1 Citrix Tools and Templates on page 2 Activity Library Design Considerations on page 3 Installation and Setup on page 5 Next Steps on page 7
Overview
Workflow 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 rehosted 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:
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 on costs 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 automatically and resolve them without the need for user interaction.
Citrix Tools and Templates

Workflow 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.
Chapter 1
PowerShell Converter
If you have a PowerShell snap-in that you would like to use in Workflow Studio as an activity 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 use PowerShell, 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 Considerations

The 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 want to 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.
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 entering credentials. 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 might need 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 (in Workflow Studio), put into a separate library, or omit.
Chapter 1
Installation and Setup

Use 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, you must 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.

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 Templates

The 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. 2. 3. Navigate to http://community.citrix.com/cdn/. Mouse over Workflow Studio in the top menu bar and choose Download SDKs. Copy WFSTemplates.msi to your development computer. 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. The installer 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.
Chapter 1
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 Steps
The 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
C HAPTER 2
This tutorial covers the tasks related to developing an activity library from a PowerShell snap-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
10
Creating a Project and Generating Activities

Note The Citrix-provided documentation for Workflow Studio does not go into detail
about 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 builtin 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 current date 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 project template 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 the PowerShell cmdlets for which you want to generate activities. You can use the PowerShell Activity Library item template to add activities to projects created by any Citrix project template. 4. Change the Name to GetDate and then click OK.
Chapter 2
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
12

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 a
new 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.
Chapter 2
11. 12.
13
To view the generated code: Right-click GetDate.cs in the Solution Explorer and choose View Code. Notice the using statements in the code.
Generated code in the GetDate.cs file

Included are references to the following Workflow Studio components. Component Common Provides 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 CustomActivityPropertyEditor CustomActivitySerializers User
Support for the customized theme in the Workflow Studio Designer. Custom file browser, folder browser, text editor, and custom binding dialog support. Helper objects to make PowerShell serializable. Base classes you can derive from when building activities to simplify access to PowerShell and WMI. Native tools to support development of UI activities. Those components are also included in the References list in the Visual Studio Solution Explorer.
14

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 Code

While 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. For
additional help, refer to the samples and comments in the generated code as well as Best Practices on page 23.
References to the Snap-in Binary

The 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, a using statement, and an ActivityReferenceAssemblies attribute.
To add references to the snap-in binary

1. To add a reference to the binary: a. b. Choose Project > Add Reference. 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.
Chapter 2
2.
15
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: 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:
[appdomain]::currentdomain.getassemblies() | sort -property fullname | format-table fullname
[ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" })]
Activity Attributes
The 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(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" })]
16

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 activity from 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.
Chapter 2
17
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 Classes

The 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("<enter new description>")] //[Category("Parameters")] //[Browsable(true)] //[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)] //public override Object Input //{ // // get { return base.Input; } set { base.Input = value; }
2. 3.
Delete the Description and Category attributes. They are not needed for a hidden input property. 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)] public override Object Input { get { return base.Input; } set { base.Input = value; } }
18
Dependency Properties
A dependency property is a property to which other activities can bind. They are the properties 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 except for Format. 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 page

23. 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. Category Determines 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.
Chapter 2
19
Reviewing Project Properties

Before 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 passwordprotected. 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 file
with your own. 4. If you change any properties, right-click the GetDate tab and choose Save Selected Items.
20
Right-click menu from the GetDate tab

5. Close the tab containing the project properties.
Testing the Activity in a Workflow

You 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. Start Workflow Studio and create a workflow that will include the GetDate activity: a. b. c. d. Click the Workflow Studio Workflows tab and then click a workflow category. (If no categories exist, you must create one.) In the Actions pane, click Create Workflow. Give the workflow a name and then click OK. When the Workflow Studio Designer opens, notice that the Activities tab does 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.
2.
Chapter 2
3.
21
To install the activity library in Workflow Studio: a. b. Choose Tools > Choose Activities. 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. b. In the Activities tab, open the Windows PowerShell > Utilities folder. It contains one activity, GetDate. Drag GetDate to the design surface. 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. b. c. d. Select the messageBox activity in the workflow. 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. Type this text, followed by a space:
The current Date/Time is:
To add the output of the GetDate activity to that text, select Output (under the getDate1 activities) and then click Add.
22
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 box

You have now completed this tutorial. The rest of this chapter contains information that will help you in creating activities from PowerShell snap-ins.
Chapter 2
23
Best Practices
Best practices for creating an activity from a PowerShell snap-in follow.
Add references to the snap-in binary

An 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 Snapin Binary on page 14.
Change optional integer properties

The 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 integer range expected to ensure that the entry is a valid integer in the correct range.
24

In the following code sample, the property changes just described are circled.
#region Year Property public static DependencyProperty 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)} )] public String Year { get { return ((String)(base.GetValue(GetDate.YearProperty))); } set { base.SetValue(GetDate.YearProperty, value); } }
Use strong names for activity libraries

Workflow 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 them

Workflow 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
Chapter 2
25
You can replace those icons with your own.
To add and reference icons

1. 2. 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). Add the icons as resources: a. 3. 4. In the Visual Studio, select the project GetDate in the Solution Explorer and choose Project > GetDate Properties. Click the Resources tab.
From the Resources tab, you can create a resources file and add the images to it. 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 needed

The 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:
protected override void 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 logic

The 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.
26

Consider the following: What you want to validate and how you want to validate it is not readily autogenerated. 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 custom activities
When you need to debug an activity that will be used in Workflow Studio, you should follow 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. Connect Visual Studio to this process... wfs.exe
To debug... Validation logic (which runs at design time, such as when you specify a property) Execution logic (for a workflow run when you click Start in the Workflow Studio Designer) Execution logic (for a deployed workflow or job)
Which is the... Workflow Studio Designer process
WorkflowExpressRuntime.exe
Process used to run workflows from the Designer
WorkflowRuntimeHostService.exe
Service the Workflow Studio uses to run jobs
Chapter 2
27
Keep the Workflow Studio Library tidy

As you test and tune an activity, you might copy the activity DLL to Workflow Studio several 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 activities
that you have added, by deleting those configuration files. However, your SQL server domain name and any other configuration changes you made will be lost.
28
Control Workflow Studio activity names

When you drag an activity onto the Workflow Studio design surface, the name of that activity 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).
C HAPTER 3
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 detail
about 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 scratch

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. 4. In the Templates list, select Activity Library. Change the Name to AdvancedDelay and then click OK.
30
New Project dialog box

A blank project opens in Visual Studio.
To add an activity to the project

1. 2. Choose Project > Add New Item. 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
Chapter 3
3.
31
To view the code: Select AdvancedDelay.cs in the Solution Explorer and choose View > Code.
Editing the Code

The 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 Attributes
The 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 Properties
You will uncomment a sample dependency property and edit it to correctly reference DelayTimeProp.
32
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 //{ // // // // // // // // //} } } set { base.SetValue(IntegerPropProperty, value); get { return ((Int32)(base.GetValue(IntegerPropProperty)));
2.
In the first line, 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. 4. 5. 6. 7.
Change the DisplayName value to DelayTime. Change the Description value to Specifies the amount of time to delay (in ms). Change public Int32 IntegerProp to public Int32 DelayTimeProp Change return ((Int32)(base.GetValue(IntegerPropProperty) to return ((Int32)(base.GetValue(DelayTimePropProperty) Change base.SetValue(IntegerPropProperty, value); to base.SetValue(DelayTimePropProperty, value);
Chapter 3
33
Activity Execution Logic

You generally should include more specific exception handling. By default, Workflow Studio 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, which

automatically 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 Logic
You 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.
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.
errs.Add(new ValidationError(@"You must specify a value for the 'DelayTimeProp' property.", 101, false, @"DelayTimeProp"));
Testing the Standard Activity in a Workflow

Follow these general steps to test the AdvancedDelayActivity. For task help, refer to Testing the Activity in a Workflow on page 20. 1. 2. 3. 4. 5. Build the activity in Visual Studio. Add the activity to Workflow Studio. In Workflow Studio, create a workflow and add the AdvancedDelay activity to it. Change the DelayTime parameter to 5000. Run the workflow.
You have now completed this tutorial.
34
C HAPTER 4
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 Attributes

This topic describes the following general activity attributes: Designer on page 35 DisplayNameAttribute on page 36 Description on page 36 ActivityTreePath on page 36 ActivityValidator 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.
36
[DisplayNameAttribute(@"name")]
Attribute allows you to specify the name for your activity. This is the name that will appear 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 separate folders 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: ImageResourceName (a 32x32 png icon/image) ShineColor GlowColor GlowIntensity BackColor MaskColor TextForeColor ShapeRadius TextFontFamily TextFontSize Width Height
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 the toolbox (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.
Chapter 4
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.
38
PowerShell-Specific Activity Attributes

This 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 before the 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.
Chapter 4
39
Dependency Property Attributes

This 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.
40
[InputAttribute]
Allows you to specify whether the property is an input type of property. Using this attribute 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 with Workflow Studio: BindingDropDownListEditor DropDownList DSComputerPicker DSGroupPathPicker DSObjectPathPicker DSOUPicker EditorHelper FileWithConstructor FolderWithConstructor NamedCollectionEditor OpenFileEditor OpenFolderEditor PasswordEditor PropertyColumnEditor StringEdit StringWithConstructor TextEditor TrusteeEditor VariableEdit
[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.
Chapter 4
41
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 may output 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 BoolString Dictionary Enumeration Guid Int Int32 IntList Long NonEmptyString Object Password PSCredential PSObject PSObjectArray String StringList Switch UInt UInt32 ULong Unknown
42

Citrix Dev Guide

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Citrix Dev Guide

Transféré par

Droits d'auteur :

Formats disponibles

Citrix Workflow Studio Activity Developers Guide

Citrix Workflow Studio 1.1

Preparing for Activity Library Development

Converting PowerShell Snap-ins to Activity Libraries

Creating Activities from Citrix Templates

Workflow Studio Activity Developers Guide

Activity Attribute Reference

Preparing for Activity Library Development

Workflow Studio Activity Developers Guide

Citrix Tools and Templates

Preparing for Activity Library Development

Activity Library Design Considerations

Workflow Studio Activity Developers Guide

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

Preparing for Activity Library Development

Installation and Setup

Adding the Required Assembly References

Workflow Studio Activity Developers Guide

Installing the Converter and Templates

Preparing for Activity Library Development

Last page of template installer

Note To uninstall the DLL and templates:

Workflow Studio Activity Developers Guide

Converting PowerShell Snap-ins to Activity Libraries

Workflow Studio Activity Developers Guide

Creating a Project and Generating Activities

To create an activity library project and convert an activity

Converting PowerShell Snap-ins to Activity Libraries

New Project dialog box

List of PowerShell snap-ins in the PowerShell Converter

Workflow Studio Activity Developers Guide

Get-Date cmdlet selected in the converter

Converting PowerShell Snap-ins to Activity Libraries

Generated code in the GetDate.cs file

CustomActivityDesigner CustomActivityPropertyEditor CustomActivitySerializers User

Workflow Studio Activity Developers Guide

Editing the Code

References to the Snap-in Binary

To add references to the snap-in binary

C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\ Microsoft.PowerShell.Commands.Utility.dll

Converting PowerShell Snap-ins to Activity Libraries

Add the following using statement:

// [ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=12345ABCD6789EFG" } )]

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

[ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" })]

Workflow Studio Activity Developers Guide

Converting PowerShell Snap-ins to Activity Libraries

Input/Output Base Classes

To hide the input property

Workflow Studio Activity Developers Guide

To edit the dependency properties

Note Dependency property requirements are described in Best Practices on page

Converting PowerShell Snap-ins to Activity Libraries

Reviewing Project Properties

To review the project properties

Project Properties window for GetDate activity library

Workflow Studio Activity Developers Guide

Right-click menu from the GetDate tab

Testing the Activity in a Workflow

To compile the code

To test the activity in Workflow Studio

Converting PowerShell Snap-ins to Activity Libraries

Your workflow should look like the following screen sample: