citrix dev guide
TRANSCRIPT
-
7/29/2019 citrix dev guide
1/46
CitrixWorkflow Studio 1.1
CitrixWorkflow Studio Activity Developers Guide
-
7/29/2019 citrix dev 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 -
7/29/2019 citrix dev guide
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 -
7/29/2019 citrix dev guide
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
-
7/29/2019 citrix dev guide
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 -
7/29/2019 citrix dev guide
6/46
2 Workf low Studio Act ivi ty Developer s Guide
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/29/2019 citrix dev guide
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
8/46
4 Workf low Studio Act ivi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
9/46
Chapter 1 Preparing for Act ivi ty Library Development 5
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
10/46
6 Workf low Studio Act ivi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
11/46
Chapter 1 Preparing for Act ivi ty Library Development 7
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
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
12/46
8 Workf low Studio Act ivi ty Developer s Guide
-
7/29/2019 citrix dev guide
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
http://../document_center.pdf -
7/29/2019 citrix dev guide
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.
-
7/29/2019 citrix dev guide
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
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
16/46
12 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
17/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 13
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
18/46
14 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
19/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 15
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" })]
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
20/46
16 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
21/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 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 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; }
}
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
22/46
18 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
23/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 19
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
24/46
20 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
25/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 21
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
26/46
22 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
27/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 23
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
28/46
24 Workflow Studio Activi ty Developer s Guide
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);
}
}
-
7/29/2019 citrix dev guide
29/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 25
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
30/46
26 Workflow Studio Activi ty Developer s Guide
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
-
7/29/2019 citrix dev guide
31/46
Chapter 2 Converting PowerShell Snap-ins to Activity Libraries 27
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
32/46
28 Workflow Studio Activi ty Developer s Guide
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).
-
7/29/2019 citrix dev guide
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.
http://../document_center.pdf -
7/29/2019 citrix dev guide
34/46
30 Workflow Studio Activi ty Developer s Guide
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
-
7/29/2019 citrix dev guide
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
36/46
32 Workflow Studio Activi ty Developer s Guide
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);
-
7/29/2019 citrix dev guide
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.
http://../document_center.pdfhttp://../document_center.pdf -
7/29/2019 citrix dev guide
38/46
34 Workflow Studio Activi ty Developer s Guide
-
7/29/2019 citrix dev guide
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.
http://../document_center.pdf -
7/29/2019 citrix dev guide
40/46
36 Workflow Studio Activi ty Developer s Guide
[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
-
7/29/2019 citrix dev guide
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.
http://../document_center.pdf -
7/29/2019 citrix dev guide
42/46
38 Workflow Studio Activi ty Developer s Guide
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.
-
7/29/2019 citrix dev guide
43/46
Chapter 4 Act iv ity Att ribute Reference 39
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.
http://../document_center.pdf -
7/29/2019 citrix dev guide
44/46
40 Workflow Studio Activi ty Developer s Guide
[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
-
7/29/2019 citrix dev guide
45/46
Chapter 4 Act iv ity Att ribute Reference 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 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
http://../document_center.pdf -
7/29/2019 citrix dev guide
46/46
42 Workflow Studio Activi ty Developer s Guide