Considerations when referencing assemblies in your page layouts

This one came up in the office last week, and I thought it worthy of discussion. On one project we have, the page layouts use the ASP.Net Register directive to reference assemblies containing our controls. So we have several directives in the code similar to:

<%@ Register TagPrefix="psw" Namespace="OurCompany.OurClient.SharePoint.WebControls" Assembly="Parity.SharePoint.WebControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=00000000000000" %>

These serve the purpose of telling the page layout about our controls assembly, and ensuring the designer can supply us with Intellisense for the controls and their members.

The question which then arises is "what happens when we update the shared assembly and we want to increment the version number? Surely we don't have to update and republish all our page layouts?" There are a couple of answers to this:

• we could use assembly redirects in application config to avoid changing the page layouts. These entries would then tell .Net to load (for example) version 2.0.0.0 of our assembly whenever version 1.0.0.0 is requested. This would work, but would mean that we don't get Intellisense for any new/changed members added in subsequent assembly versions.


• we could also avoid referencing common assemblies in this way completely, and centralize the reference in web.config instead

So instead of having an entry in each page layout, the 'Pages' section of web.config (in .Net 2.0 and upwards) allows us to reference assemblies containing controls in one central place, meaning any changes to the assembly name are simple to implement:

<pages>
  <controls>
    <add tagPrefix="psw" namespace="OurCompany.OurClient.SharePoint.WebControls"
         assembly="OurCompany.OurClient.SharePoint.WebControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=00000000000000" />
    <!-- also works with short assembly name -->
    <!--
    <add tagPrefix="psw" namespace="OurCompany.OurClient.SharePoint.WebControls"
         assembly="OurCompany.OurClient.SharePoint.WebControls" />
    -->     
  </controls>  
</pages>

[Side note] - as I specify in the comment, it is possible to reference the assembly with the short name, but shops with a defined versioning strategy will want to avoid this since it's then not possible to have side-by-side versions of assemblies, one of the fundamental forward steps introduced with .Net.

However, it's not all clear cut. Unfortunately SPD isn't clever enough to resolve the assembly reference in web.config to provide Intellisense. I initially thought it was, but alas closing and re-opening shows that in fact something was cached. Visual Studio is sufficiently aware (if we were in a pure .Net scenario), but not SPD.

So it's a trade-off as far as I can see - either have the @Register directive in your page layout (with version numbers in it), or reference in web.config but lose Intellisense.

I wondered if it was possible to use the short assembly name in the @Register directive, but supply a 4 part assembly name in web.config for use at runtime. Unfortunately this doesn't work since .Net sees it as an ambiguous registration. So if you want to keep assembly version numbers out of your page layouts but keep Intellisense, one strategy could be to remove the @Register directives as part of your release process.

Or as an alternative final thought - which is more important, Intellisense during development or minimising running into this problem at release time? For my money, losing the inconvenience of Intellisense in SPD for controls in is a minor hassle, so referencing assemblies in web.config is a better approach.

5 things you didn't know about me

So a full year after it started, this tagging thing is still going on - my buddy Robin Meuré has tagged me to write about things you didn't know about me. I figure since I've not done this yet and I rarely write about anything personal, I'd make an exception and do it - so here goes. I think I'm actually supposed to write 8 facts, but 5 seems plenty to me :-)

1. I'm completely addicted to breakfast cereal!
   
   I love muesli in particular, and for the last 10 years have got through at least two big bowls a day when not away from home. Those who have me on Messenger might know this from the Chris O'Brien : ICerealizable tag (developer's joke :-)) Bizarrely, my girlfriend Suzanne is a buyer for an organic muesli company, and so is able to bring lots of free stuff home, woohoo! Shortly after we met a couple of years ago, I remember in the pub my friends asking what she did as a job - when I told them, they didn't believe me ;-)
   
   
2. I used to be a competitive cyclist.
   
   In my teens my life was dominated by cycling. I won lots of races when I was at my peak at around 18, and wasn't too far off getting into the GB team. Unfortunately my sporting career was cut short due to the combination of a couple of bad crashes in races and discovering girls and pubs. Guess I probably didn't have the dedication required to make it at the top level.
   
   
3. I got into computers by accident.
   
   I studied business (and French!) rather than a classic Computer Science degree. The third year was a 'year in industry', and I'd talked my way into a prestigious placement in the IT department of large blue-chip. I hated it. I didn't understand the technology (IBM AS/400) and everyone spoke a language I didn't understand. After 5 months of unhappiness, it dawned on me that if I threw myself at it I'd probably understand it, and if I understood it I'd probably like it. I studied OS/400, Query 400, JD Edwards etc every evening, and 2 or 3 months later I absolutely loved it. I didn't want to return to university at the end of the year and was tempted when my employer said there'd always be a job for me there.
   
   
4. I love travelling.
   
   My backpacking days are probably over, but I've been lucky enough to travel around South America, Australasia and Asia. The most recent trip was a solo trip to Nepal just over a year ago, and I got to trek to Annapurna base camp which is used for climbing expeditions in the area. At the higher altitudes it was getting down to -16 °C at night, and of course the simple lodges used for shelter at night have no heat! Those nighttime trips in the howling wind to get to the toilet were pretty memorable.   
   
   
5. I'm a big Manchester City fan.
   
   Although I've lived in London for many years, I'll always support the 'other' team from Manchester and for better or worse, this was handed down from my father. If you speak to many people from Manchester, they'll always tell you real Mancunians support City. Unfortunately it's frequently a despondent hobby, and Colin Schindler had it right when he wrote his book 'Manchester United ruined my life'. However, I'm encouraged to read there is apparently an entire village of Manchester City fans somewhere in Sierra Leone!
   

So that's me. Some other people I'd like to tag who I don't think have done this are:

• Vince Rothwell
• Ben Robb
• Andrew Woodward
• Zac Smith
• Mikhail Dikov

Accelerate your InfoPath managed code development

Like most developers, I'm always looking for ways to speed up the code/test/get feedback cycle. There are many ways to do this in SharePoint development, and I guess a typical example would be to do application pool recycles rather than full IISResets. Along similar lines, anyone who has spent time doing Visual Studio/WF workflow development in SharePoint would hopefully have discovered the DEPLOY QUICK parameter on the build script MS supply - this will simply GAC the updated workflow assembly rather than perform a full deployment of the workflow Solution/Feature. This alone will probably shave many hours off a significant workflow project.

When working with InfoPath forms which have managed code, we need to deploy as an administrator-approved form rather than publish directly to a list or content type. The process is:

• publish the form to the filesystem
• upload the form via 'Manage form templates' in Central Admin

In the background, the last step actually wraps the form .xsn and associated assembly in a Solution and Feature, and deploys throughout your farm. Understandably this is S-L-O-W for development, so I started looking at ways to speed this up. Interestingly the assembly doesn't get deployed to the GAC or web application bin directory, but resides solely in the folder for the Feature (click image to enlarge):

Nevertheless, instead of publishing the form we can do the following:

• compile VSTA/VSTO project
• copy .dll (and .pdb if we're in debug mode) over the ones in the Feature folder
• recycle app pool

This will then load the updated code. Note because we've only deployed the updated code to the local machine, only form sessions on the local machine will be affected (I'm assuming you're not using a load-balanced URL in dev) - this has a nice side-effect of isolating your changes from other developers in the farm until you're ready to release them.

I'm interested to know how InfoPath accomplishes the trick of loading assemblies from this location at run-time -there are no custom 'probing' entries in my web.config (instructions to tell .Net to probe custom locations for assemblies) so I'm assuming it's done via reflection.

If you have your own tips for speeding up SharePoint development which aren't commonly-known, I'd be interested to hear...

Recipe for successful use of Content Deployment Wizard

So my tool, the SharePoint Content Deployment Wizard has been available for some time now and I've been monitoring the feedback and issues people have raised closely. The current version is labelled 'beta 2' but I'm happy with the stability of the current codebase, so will probably re-label it as 'release 1.0' soon (following some feedback on the psychological aspect of the beta label :-)).

Only a small number of people have raised issues, and any problems have almost exclusively been related to the underlying Microsoft code used by the tool rather than the Wizard itself. I should probably be happy about this, but in reality if some people get errors from the tool it doesn't really matter why it happens. The good news is that it seems Microsoft are finally getting some issues with the Content Deployment API sorted at their end. This is a key point in my list of guidance I'd give to anybody running into any errors from the Wizard. Note that the first two apply to use of standard Content Deployment using Central Admin also:

Tip 1 - Service Pack 1 and hotfixes matter

Service Pack 1 fixed many issues with Content Deployment. Unfortunately it also broke some things which had previously been fixed with pre-SP1 hotfixes. It took me a while to realize this, but it's definitely the case. Probably the most common issue in this area is the 'Violation of Primary Key' error. There are reports of being able to work around this by modifying versioning settings on certain libraries, but MS have now released a hotfix very recently which seems to solve the problem for good on SP1 environments. At the moment this is by special request only - the KB to ask for is KB950279. This forum thread discusses this, and it worked for us. Interestingly I spoke to Tyler Butler (Program Manager for Content Deployment) at SPC2008, and he indicated Content Deployment in SharePoint is likely to get "significantly more stable in the next 30-60 days". I'm guessing this hotfix is what he was referring to, or at least part of it.

Tip 2 - always start from a blank site template an empty site created from STSADM -o createsite on the destination

The official guidance currently states that Content Deployment requires that the target site has been created from the 'blank' site template - this is detailed in KB article 923592. However, a better way detailed by Stefan in the comments below is to create an empty site using the STSADM -o createsite command. This is not the same as a site created from the blank template, and is the safest way to create sites which will use Content Deployment or the Wizard. What this means is that even if you're creating a site based on say, the publishing site template in development, any other environments which you wish to deploy content to should be created in this way. Notably, for publishing sites the publishing Feature should also not be enabled for the first deployment - this will be taken care of for you when the first deployment happens. You'll receive the same 'object already exists' error otherwise.

Tip 3 - pay attention to the 'retain object IDs' option

Generally the right option here is to select that you do want to retain the object IDs, and this should be done from the very first deployment - the only exception is when moving webs/lists to a different part of the site structure (reparenting). However, it's important to note that mixing use of Content Deployment or the Wizard with STSADM export/import is likely to cause problems as noted by Stefan in his recommended 'Content Deployment and Migration API - avoiding common problems' post.

A more comprehensive write-up of options available with the Wizard is available at 'Using the SharePoint Content Deployment Wizard'. Also note that's not it as far as the tool goes - in addition to extra functionality such as item-level reparenting and incremental deployment, I hope to refactor the code so that the Wizard would be scriptable from the command-line.

And special thanks go to my colleague Nigel Price for working through the hotfix situation, much appreciated :-)

This blog is changing URL..

..but I'm hoping you won't notice! The new URL is the somewhat simpler www.sharepointnutsandbolts.com, and if everything goes to plan everything will be redirected from old to new, so any bookmarks should continue to work. Or that's the theory promised to me by my blog host, but I thought I should say something just in case :-) Certainly all subscribers to the feed won't need to do anything - the Feedburner URL will stay the same.

Changeover will be later this week - if anybody notices a problem I'm keen to hear, please drop me a comment to let me know!

P.S. I'm likely to switch over to using the CKS : EBE framework at some point soon. A few people have commented that since we moved into 2008, they found it harder to find articles since the navigation on the right buries them under the '2007' node. I've tried to mitigate this by adding the 'Most popular articles' list (as indicated by Feedburner), but I know navigation isn't ideal. Rest assured I'll improve it when I have more control over the site!

Great controls to be aware of when building SharePoint sites

Something I've been meaning to do for a while is discuss some of the controls I've found useful when putting together SharePoint sites. Obviously before building a custom control for a specific behaviour, it's a good idea to check if SharePoint comes with anything that will do the job. It sometimes surprising what you find! Certainly those from a Content Management Server background will be familiar with the idea of having lots of reusable controls (which used the CMS API) within the team, but in MOSS some of the equivalent controls come for free. The most obvious is the Content by Query web part (though we won't mention that the output HTML isn't accessible [WCAG AA-compliant] without extra work), but some of the smaller controls deserve some attention too. So here's a rundown of some handy items for the toolbox:

SPSecurityTrimmedControl

This control can be used to selectively display content or controls depending on the current user's SharePoint permissions. Whatever is the inner content of the control will therefore not be shown if the user doesn't have the specified permissions. An example would be:

   1: <SharepointWebControls:SPSecurityTrimmedControl runat="server" Permissions="ManageWeb">

   2:     This is only visible to users who can manage current web..    

   3: </SharepointWebControls:SPSecurityTrimmedControl> 

In addition to the Permissions property shown above (enum), the PermissionsString property can be used to specify a comma-separated list of required permissions. This can be used in conjunction with the PermissionsMode property which takes 'All' or 'Any', and also the PermissionContext property which specifies what SharePoint object (e.g. 'CurrentList', 'CurrentFolder', 'CurrentItem', 'CurrentSite', 'RootSite') the specified permission applies to, so it's flexible. Examples of the permissions which can be specified include 'ManageLists', 'AddListItems', 'ViewPages', 'ManagePermissions' and so on. These are members of the SPBasePermission enum and Zac Smith has a full list. Notably many of these permissions are probably more useful in a collab scenario rather than WCM. [UPDATE: Text in this section updated following comment below/further testing:] For WCM folks the control does look like it does something useful in being able to filter on authentication type - unfortunately this doesn't work as advertised. For reference (in case MS fix it), the usage is:

   1: <SharepointWebControls:SPSecurityTrimmedControl runat="server" AuthenticationRestrictions="AnonymousUsersOnly">

   2:     This *should* be visible only to anonymous users but it doesn't work..    

   3: </SharepointWebControls:SPSecurityTrimmedControl> 

As you'd expect, valid values here are 'AnonymousUsersOnly', 'AuthenticatedUsersOnly' and 'AllUsers' - however as noted in the comments below 'AuthenticatedUsersOnly' is the only flag which seems to work properly.

There are some other interesting properties too:

• PagesMode - valid options are 'Design', 'All' and 'Normal'


• QueryStringParametersToInclude


• RequiredFeatures

These look like extra properties to filter on, but alas I couldn't get these to work either. My investigative powers let me down here as firing up Reflector onto both SPSecurityTrimmedControl and the related RightsSensitiveVisibilityHelper class didn't give anything away in terms of usage, nor did Google or searching the 12 hive. Certainly it looks like specifying values is all that would be needed for latter two parameters, but I had no joy. A final consideration for SPSecurityTrimmedControl however, is the idea of further possibilities opened by deriving from this control in the same way SPLinkButton does.

EditModePanel

Where the previous control examined the user's permissions to establish whether content should be shown, the EditModePanel looks at whether the current page is in display or edit mode. This can be incredibly useful in the WCM world for displaying help messages or other content to users as they edit a page. However there are other uses - hiding navigation, adding inline CSS override classes to use different formatting (particularly useful) and emitting debug information in the HTML output are all examples. The declaration for this control would look like:

   1: <PublishingWebControls:EditModePanel SuppressTag="false" GroupingText="Title help" 

   2:         PageDisplayMode="Edit" runat="server" id="EditModePanel1">

   3:     Page titles should be concise

   4: </PublishingWebControls:EditModePanel>

At run time in edit mode, this would look like:

A prettier usage might be to include the field controls within each respective EditModelPanel, meaning the input control is shown within the borders of the box. To do this we'd also need an extra EditModePanel set to PageDisplayMode="Display" which also contained the field control, since the original will display in edit mode only. Note this control will output a surrounding <div> unless the SuppressTag property is set to 'True'.

ListItemProperty

One control you might use in conjunction with the previous control is the ListItemProperty control. This simple little fella allows you to write out a particular field's value for a list item. The field which is rendered is specified with the Property attribute, where we specify the field's internal name. By default, the current list item (i.e. for the page we're viewing) is used, but this can be overridden by specifying the List property - to do this we specify the list GUID with braces:

   1: <SharePointWebControls:ListItemProperty runat="server" id="ListItemProperty1" 

   2:     List="{C110296D-2BE9-4818-80EE-A06BD018DE2F}" ListItemID="1" Property="Title"/>

I think of this control as doing a .ToString() on the contents of the chosen field. This can sometimes be useful in WCM where you want the value to appear in a different location onthe page to where it is edited - for example within a <title> tag. Note we can also specify the version of the list item we want to retrieve the value for with the ListItemVersion property.

ListProperty

Much the same as ListItemProperty except on a list itself. These two may well be used together as the code in a list's DispForm.aspx does:

   1: <SharePoint:ListProperty Property="LinkTitle" runat="server" id="ID_LinkTitle"/>

   2: : 

   3: <SharePoint:ListItemProperty id="ID_ItemProperty" MaxLength="40" runat="server"/>

This will show the current list's title, followed by a colon, followed by the current list item's title.

ProjectProperty

Slightly confusing name, but this control allows us to write out some properties of the current site/web. The MSDN documentation shows the valid list to be:

• BlogCategoryTitle - Category of the current post item


• BlogPostTitle - Title of the current post item


• Description - Description of the current Web site


• RecycleBinEnabled - 1 if the recycle bin is enabled; otherwise, 0


• SiteOwnerName - User name of the owner for the current site collection


• SiteUrl - Full URL of the current site collection


• Title - Title of the current Web site


• Url - Full URL of the current Web site

So the following would write out the title of the current web:

   1: <SharePointWebControls:ProjectProperty runat="server" id="ProjectProperty1" 

   2:     Property="Title" />

DelegateControl

This control provides an architecture where an 'outer' control is added to the page layout/master page, but the 'inner' control is determined by a Feature, thus allowing the control to be swapped out without having to modify the original template. This is used widely in Microsoft's master pages. This is a great control, I discuss it more fully in my Using the DelegateControl post.

AssetUrlSelector

To finish on something slightly different, this control can be invaluable when developing custom web parts and field controls. It provides the 'file picker' experience authors are used to when working with SharePoint, and fits well when you have a control which requires a file to be selected. So in several of my controls I allow the user to override the XSL file used for formatting, and the AssetUrlSelector is added to the user control I use for the edit view of the control. This provides me with the 'browse' button which will launch the picker when clicked:

 
Clicking the button then shows:

 
The AssetUrlSelector provides a fairly good user experience, including opening the picker in the location of the currently-selected file if one exists, or defaulting to a specified default location if not. Along similar lines if you need to provide a slick experience to select an image is the RichImageSelector - this is the picker used by the RichImageField control.

Summary

So that's some of the controls I've found useful. Obviously there are stacks more and the ones I did highlight can be used in lots of interesting ways which aren't discussed here. But hopefully this does serve to remind you to check what's in the box before spending time writing your own!

New version of Content Deployment Wizard released

I'm happy to announce that development/testing of the next version of the SharePoint Content Deployment Wizard is now complete, and the new release has been uploaded to Codeplex. If you're not aware of the tool then Introducing the SharePoint Content Deployment Wizard is a good place to start. I'm calling this release "beta 2", which indicates the tool is by no means complete, but is significantly more mature than the original version. I'd encourage all of the 1400+ people (and counting) who downloaded the original in the past few weeks to get the latest version - the link is at the bottom of this post.

So let's run through the improvements:

• Better support for large sites:
  
  The treeview of the site is no longer built in one hit - instead, portions of the site are retrieved as webs/lists are expanded. This can make a huge difference when working with large sites.
  
  
• Support for WSS-only sites:
  
  The dependency on the MOSS assembly (Microsoft.SharePoint.Publishing) has now been removed, so imports/exports to WSS sites are now possible. The MOSS-specific functionality is only used if we are indeed in a MOSS environment - if you're interested, this is just related to honoring any publishing schedules (i.e. page expiry) from the source site on the target site.
  
  
• Everything in one .exe:
  
  No separate WizardBase.dll any more.
  
  
• Easier access to log files after import/export:
  
  Since it's highly important to analyze the log file for errors/warnings after an import/export, these now open automatically in notepad at the end of the operation. There's also a link in the tool to open the log file, so no more manual digging around the filesystem.
  
  
• Auto-discovery of sites in 'Site URL' box:
  
  No need to re-enter the site URL each time - the sites available for selection in your SharePoint environment are automatically shown in the auto-complete entries for the textbox:
  
   
  
  
• Pretty icons in treeview :-)
  
  Easier visual distinction between objects in the tree:
   
  
  
• Logging via System.Diagnostics.Trace:
  
  In addition to the log file generated by the actual import/export operation, general operations in the tool are now also logged (separately) via System.Diagnostics. So if you have a problem using the tool, it should be easier to pinpoint the actual error - enable by adding a .config file with a TraceSwitch entry for "COB.SharePoint.Utilities.ContentDeploymentWizard" and appropriate TraceListener entries.
  
  
  
• More reliability:
  
  Miscellaneous minor bug fixes, including removal of the somewhat psychedelic flickering as the confirmation screen is built.

In terms of issues reported in the first release, it seems that 95% of them have been related to the underlying Content Migration API provided by SharePoint rather than the actual Wizard - this means the issue would also likely surface if out-of-the-box Content Deployment (via Central Admin) or STSADM -export was used to deploy the content instead. This is in line with what I was expecting since in many ways the Wizard doesn't actually do that much - it just presents a nice UI (with the ability to cherry-pick exactly which items should be deployed) onto existing SharePoint code. Since there are some gotchas with the MS bits however, it does mean that understanding how their API works can help when using the Wizard. My recommended reading list for those wanting to know more would be:

• Using the Content Deployment Wizard
• Stefan's Content Deployment and Migration API article series (especially Avoiding common problems)
• Key concepts in selective migration (SharePoint Developer Documentation team blog)
  

The future

I've had great feedback so far (ranging from feature requests to "why the hell don't you charge for this thing?!" to offers of collaboration). In terms of features, it looks like incremental deployment is the most popular vote so far so I'm hoping to add this fairly soon. Another possibility is making the Wizard scriptable by refactoring the code into something more tiered, thus providing features like the ability to save configurations for import/export jobs and also allowing them to be hooked up to a task scheduler in some way. 

However, the more feedback the better and if you'd like to see particular functionality or have run into problems trying to use the tool I'm definitely keen to hear. Either leave a comment on the blog or over at the Codeplex site.

The download link 

Go to www.codeplex.com/SPDeploymentWizard and go to the releases tab to download the latest version. Hope you find it useful.

More workflow issues and resolutions

What I wanted to do today is run through is wrap up my series of workflow posts, by running through some of the issues I hit during development. If you're into workflow, you may have seen Rob Bogue's excellent 10 issues (and resolutions) for SharePoint+Workflow - this post is something of an extension to Rob's. It probably makes for rather dry reading, but will hopefully be useful to those Googling for specific problems.

1. Issue:- Error message "System.Xml.XmlAttribute is not serializable" shown in workflow history list and workflow will complete before it is supposed to. In SharePoint log, will see "End of Stream encountered before parsing was completed” error.
   
   More information:- This is caused by trying to store a class which cannot be serialized as a member (e.g. private variable) of the workflow class. Furthermore, I also encountered this error when storing the class which represents the InfoPath form - interestingly this class will always definitely be serializable, but the error was happening nevertheless.
   
   Resolution:- Mark member as NonSerializable (so workflow does not attempt to serialize the class, and copy primitive data (e.g. strings, dates etc.) out of form class and into individual field-level variables. It might also be possible to mark the ‘AnyAttr’ member of the generated class as NonSerializable instead.
   


2. Issue:- InfoPath forms do not get updated upon solution deployment - changes are not reflected.
   
   More information:- This happened when I initially started development. I noticed that if I separately deactivated/uninstalled the workflow Feature, the InfoPath forms would then update successfully. This pointed me to an issue with the PostBuildActions.bat script.
   
   Resolution:- Modify PostBuildActions.bat to use the -force parameter when deactivating/uninstalling the Feature.
   


3. Issue:- Error message "The e-mail message cannot be sent. Make sure the outgoing e-mail settings for the server are configured correctly." is shown in the workflow history list. E-mail configuration is known to be good (e.g. alerts are working).
   
   More information:- I suspect there are several reasons why this may happen, but for me the problem was how I was using the SendEmail activity. When I was setting properties on the SendEmail variable the workflow designer had added to my class for me, I had the error.
   
   Resolution:- The best way I found to deal with this was to set properties on the object which is passed to the SendEmail's 'MethodInvoking' code. You'll need to cast to SendEmail before you can do this.
   


4. Issue:- The TaskID for a CreateTask activity does not get populated. The value defaults to -1 instead.
   
   More information:- This will be an issue in several scenarios, one example is when building the URL for a task (e.g. to include in an e-mail to a user) with code similar to Paul Hunt's code shown at http://suguk.org/forums/thread/4978.aspx.
   
   Resolution:- The TaskID will only be populated if there is a place to store the value. Ensure the TaskID property on your CreateTask activity is bound to a variable.
   


5. Issue:- Error message "Correlation value on declaration 'x' is already initialized" message shown in SharePoint log when a task executes for the second time in a workflow.
   
   More information:- This scenario can happen when a CreateTask runs for a 2nd time due to an approver rejecting something in the workflow.
   
   Resolution:- The 'OwnerActivtyName' of the task's correlation token is incorrectly set. In a state-machine workflow, it should refer to the particular state, not the overall workflow.
   


6. Issue:- Unexplained errors when some part of an otherwise functioning workflow is commented out in the designer (e.g. 'Failed on start').
   
   More information:- You've commented out one or more activities in your workflow (using right-click > Disable), but observe strange behaviour and/or errors. This is actually because, in contrast to commenting out source code, the code is actually still compiled into the assembly. Hence if there is an error with say, a correlation token being incorrectly set, this will still cause a problem in your workflow.
   
   Resolution:- Fix problem or remove faulting activity/activities completely from workflow.

For completeness, some other common issues which are well documented in other sources are:

• 'Failed on start' - this often caused by a problem loading the workflow assembly. Check the PostBuildActions.bat script (or whatever you are using) has properly deployed the assembly to the GAC, and all the assembly attributes (version, public key token etc.) match those specifed in the Feature files.
• 'SPException: This task is currently locked by a running workflow and cannot be edited' message. This is documented by Rob Bogue and others, but I'd also add this can occur as a knock-on effect of another problem. If an earlier exception has occurred whilst trying to process a task, the workflow will have locked the task on the first run, meaning that subsequent attempts by a user to respond to the task will result in this error. Other than fixing the problem at source, I haven't found an elegant way of dealing with this.

So hopefully that's of some use to workflow developers. If you haven't seen it already, there's a lot more goodness (sample code, tips and tricks etc.) in my workflow resources pack from the workflow deep-dive presentation I did at the UK SharePoint user group earlier this year.

Happy coding!

InvokeWorkflow - child workflows not supported in SharePoint?

Our client through an interesting curve ball at us midway through my workflow project. We were probably 70% code complete, when it was realised the design had no provision for a certain scenario. The workflow is triggered by a user completing an InfoPath form - this has many input controls to collect data, and several of them are dropdowns which dictate the particular path through the workflow which occurs. One such dropdown looks something like:

Type:

• type 1
• type 2
• both

The value selected is evaluated by IfElse conditions in the workflow - if "type 1" is chosen, we go down a particular branch, if "type 2", a different branch and so on. Now for this particular dropdown, we realised we hadn't specified what should happen for the "both" condition (that's agile for you!). The new requirement which arose was that notifications and tasks should go to to two teams (i.e. both of them), and after further discussion we decided it would be appropriate to kick off two separate workflows, one for each team.

Most workflow frameworks can deal with this by using 'child' workflows, and Workflow Foundation is no different. After a couple of hours refactoring the implementation to use this approach, my proof-of-concept looked like:

So whilst the 'InvokeWorkflow' activities are closed (i.e. the child workflows aren't expanded), you can hopefully see that if we go down the branch on the left, we launch one child workflow, but in the branch on the right (for "both"), we launch two child workflows in parallel.

The problem

I tried a couple of things, the image above shows using a sequential parent workflow (though the child workflow is state-machine), but couldn't get this to work. Using the debugger I could see that the child workflows were being initialized - I could step through InitializeComponent(), but breakpoints in 'OnWorkflowActivated' were never hit - the event wasn't raised. The SharePoint log showed:

System.Workflow.Activities.EventDeliveryFailedException: Event "OnWorkflowActivated" on interface type "Microsoft.SharePoint.Workflow.ISharePointService" for instance id "67c4929a-9280-4b8b-9a4c-a1b85b04267c" cannot be delivered. ---> System.InvalidOperationException: Event Queue operation failed with MessageQueueErrorCode QueueNotFound for queue 'Message Properties Interface Type:Microsoft.SharePoint.Workflow.ISharePointService Method Name:OnWorkflowActivated

So I became suspicious of whether it's possible to use InvokeWorkflow in a SharePoint workflow. Microsoft haven't yet got back to me on this, and the most detailed SharePoint workflow book I'm aware of (Workflow in the 2007 Microsoft Office System by David Mann) does not discuss InvokeWorkflow.

Time for some lateral thinking.

The solution

We know that we will definitely have two workflows if two completed InfoPath forms are added to the document library, so I asked the client what they thought of getting the system to split a "both" request into two separate items - this would mean having two separate InfoPath forms in the list. The answer was "actually that's probably better for the users come to think of it", so the solution I came up with was:

• a list event receiver which executes before the workflow - this does the following:
  - opens the binary contents of the InfoPath form as a string, and modifies the dropdown value from "both" to "type 1"
  - creates a duplicate of the original file in the same library, but modifies the dropdown value here from "both" to "type 2"
• running some ad-hoc code to reorder the event receivers on the list - we need to split the item before workflow starts (so we get two workflows) but SharePoint adds the SPWorkflowAutostartEventReceiver at sequence of 1 so it executes first. This code switches the event receiver sequence so our pre-processing happens first.

On the last point, I considered that the SharePoint team may have set workflow to execute first for a reason, but then again it's just another event receiver and SharePoint does not prevent this reordering (in the same way it does with some other changes, such as deleting the welcome page from a web for example). In any case, we've tested pretty extensively and the solution hasn't missed a beat.

In case it's useful, the following code can be used to duplicate and modify a file - this could be used in a list receiver (as in my case) or in ad-hoc code. I used simple string manipulation to perform the modification since InfoPath forms are just XML, and also because using XML-handling methods caused issues with the 'proprietary' InfoPath declarations. Simply replace the string replacement line with your own processing.

   1: private string getFileContentsAsString(SPFile file)

   2: {

   3:     byte[] aFileBytes = file.OpenBinary();

   4:     string sContents = Encoding.UTF8.GetString(aFileBytes);

   5:  

   6:     return sContents;

   7: }

   8:  

   9: private void duplicateFile(SPListItem originalListItem, string sNewItemUrl, 

  10:     bool bDeleteOriginal)

  11: {

  12:     SPFile originalFile = originalListItem.File;

  13:     string sOriginalFileContents = getFileContentsAsString(originalFile);

  14:  

  15:     // TODO: replace this line with your own processing..

  16:     string sNewFileContents = sOriginalFileContents.Replace("oldValue", "newValue");

  17:     

  18:     byte[] aNewFileBytes = Encoding.UTF8.GetBytes(sNewFileContents);

  19:  

  20:     // we effectively need to add a new file for this operation, and optionally delete 

  21:     // the original..

  22:     SPFile newFile = originalListItem.ParentList.RootFolder.Files.Add(sNewItemUrl, aNewFileBytes,

  23:                                                                       originalFile.Properties);

  24:     newFile.Update();

  25:     

  26:     if (bDeleteOriginal)

  27:     {

  28:         originalListItem.Delete();

  29:     }

  30: }

P.S. If anyone is using InvokeWorkflow in a SharePoint workflow, leave a comment :-)

Workflow: tasks which can only be actioned by task owner

When coming to Visual Studio workflows, something which surprises many SharePoint developers is that tasks assigned in the workflow can actually be actioned by any SharePoint user with basic permissions. In the worst scenario, 'basic permissions' means any user with contribute permissions to the SharePoint web which contains the workflow tasks list, and clearly this could be a whole lot of users who have nothing to do with your workflows. In the best case, you might have tied down permissions so that only users involved in workflows can use the list. Even so, this still means that any actor in the workflow can respond to any task, not just tasks which have actually been assigned to them. To my mind, this is bad - all it takes is a confused user to accidentally respond to someone else's task and your workflow is in a whole world of chaos.

So what can we do about this?

Well, there doesn't seem to be much written about this, but fortunately the best solution (AFAIK) is also the simplest one. Before we dive in, I notice other people needing to solve this problem have taken the approach that since a workflow task is just a list item, we can execute some code to set permissions on the list item using the API. A logical tactic, but happily there is special provision for doing this in the workflow framework - we still need to write a little code, but it's much simpler than that approach. The key is the 'SpecialPermissions' property of the CreateTask activity:



Pitfall - confusingly, clicking the ellipses button (...) for the property presents a generic VS collection editor (shown below), which as far as I can tell just flat cannot be used with this property - all the controls are disabled!

I'm assuming this is a bug in the Visual Studio 2005 Extensions for Workflow Foundation, so we'll ignore that! However, clicking the tiny blue 'bind property' button presents the more familiar 'bind the property to an instance variable' dialog - assuming you haven't already created a variable to store the permissions for this CreateTask, we should select 'Bind to a new member', and create either a field or property to store the permissions:



This creates a collection object, specifically a HybridDictionary, to which we can add items for each permission we need for this task. And we only need a handful of code lines to do it! Since we're likely to use it for many (i.e. all) tasks in our workflow, let's have a separate method we can call each time:

private void setTaskPermissions(HybridDictionary boundDictionary, string sTaskOwner)

{

     boundDictionary.Clear();

     boundDictionary.Add(sTaskOwner, SPRoleType.Contributor);

     boundDictionary.Add("NT AUTHORITY\\authenticated users", SPRoleType.Reader);

}

So, we pass in the collection specific to each task, and also the string username for the task owner. We then add an entry for the task owner to the dictionary with the 'contributor' permission, and one for all other users with just read permissions. Note we also clear out the dictionary before adding in case this task has already been issued (i.e. something got rejected in the workflow and we came back to this task a second time) - this avoids any errors due to the key already existing in the dictionary.

The calling code then, looks like this:

setTaskPermissions(approveExpenseClaim_SpecialPermissions, taskProps.AssignedTo);

This would be added to the code for each CreateTask activity in your workflow. The first parameter is the variable we bound earlier to the SpecialPermissions property (of the particular task we are dealing with), and taskProps is the SPWorkflowTaskProperties object which holds data for the task.

And that's it - much less code than you'd need to modify permissions for the list item with general API usage. The effect of this is that the task owner is the only standard user (administrators with full control excepted) who can respond to the task, but all others can read it. Needless to say, you could customize the code to your specific permission requirements if they are different to mine.

The user experience

One final thing worth pointing out is that the user experience might not be quite as slick as you'd like. Since we've restricted permissions on the item, any user who clicks on the task but doesn't have permissions will see the standard access denied message:

Personally I think an improvement would be to show a more friendly message, but this would require substantially more effort and complexity. My view is that for a few lines of code, this approach is a great trade off between effort required and benefit of protecting the integrity of the workflow - I'm definitely not a fan of sleepless nights wondering just what would happen in the workflow if users unintentionally responded to tasks which didn't belong to them, so it works for me. As always, if you've implemented a different way of dealing with this problem or have other comments, it would be great to hear.