Paul Ryan

SharePoint 2013 Certification Overview

A colleague of mine, Ari Bakker, recently posted about the new SharePoint 2013 certification road map. As it represents a significant change, especially for developers, it is definitely worth understanding if you plan on getting certified in the future. Check it out here.

SPFileVersion: Handling SharePoint file versions programmatically

I recently had a requirement around linking to and downloading specific versions of documents stored in SharePoint. There is some rather quirky behaviour around SPFileVersion and how this is achieved and I felt it warranted a post.

The first thing to be aware of is that there are two distinct version collections: SPFileVersionCollection and SPListItemVersionCollection. These collections can be accessed via the respective assets as you would expect (SPFile.Versions and SPListItem.Versions) and, as is the way in SharePoint, are enumerations of SPFileVersion and SPListItemVersion objects, respectively. These objects, which represent the individual versions, have a number of similar properties and methods but do not share a base class nor an interface.

In order to access specific versions of documents, the approach I took was to store the VersionLabel (a property on both SPFileVersion and SPListItemVersion) and then retrieve the version by using this value in conjunction with GetVersionFromLabel (a method on both SPFileVersion and SPListItemVersion). This works but with a number of caveats:

SPFileVersionCollection does NOT contain an entry for the latest version. This means that if the document has only a single version then this collection will be empty. If you want to access the latest version you must verify that the version label refers to the latest version by comparing it to the first entry in the SPListItemVersionCollection and if it is then access the SPFile directly. If you are accessing properties that are also present on an SPListItemVersion (ie not opening a stream) you can use that collection instead but you must also take note of the next point.
SPListItemVersion.Url behaves unexpectedly in some situations. Assumedly this is to support directing underprivileged users away from minor versions that they are not allowed to see (although I don’t see how it achieves this), the Url for minor versions will be equal to that of the latest minor version when there is no published version. Always use SPFileVersion.Url.
Minor versions get promoted when published, breaking links to the minor version. Example – You have a document currently at version 0.2, with a previous 0.1 version. When you publish this document you still only have two versions: 0.1 and 1.0. You will now fail to locate version 0.2. Don’t be fooled into thinking that using the VersionId property will solve this issue. It simply represents the the version label as an integer (+1 for each minor version, +512 for each major version). The only way I could find to handle this case is to introduce the doc store version which is stored in the property bag of the SPFile: SPFile.Properties["vti_docstoreversion"]. You can see how this works by looking at the code examples I have included but if this specific case isn’t going to be an issue for you then don’t use it and enjoy cleaner code (see here). Also note that the doc store version is only stored in the SPFile property bag and not in the SPListItem property bag.

I have included some code to illustrate how this may be implemented:

public static string GetUrlForVersion(this SPListItem item, string versionLabel, int? docStoreVersion = null) { string relatedDocumentVersionUrl = string.Empty; // This check is done in SPFile.GetFileVersion (so we could only perform it when we know we don't have a file) // but we do it here first to save effort in the case that we aren't working with a file (to save that more expensive check). if (string.IsNullOrEmpty(versionLabel)) { relatedDocumentVersionUrl = item.Url; } else { SPFile file = item.File; if (file != null) { SPFileVersion fileVersion; bool refersToLatestVersion = file.GetFileVersion(versionLabel, out fileVersion, docStoreVersion); if (refersToLatestVersion) { relatedDocumentVersionUrl = item.Url; } else if (fileVersion != null) { relatedDocumentVersionUrl = fileVersion.Url; } } if (string.IsNullOrEmpty(relatedDocumentVersionUrl)) { var itemVersion = item.Versions.GetVersionFromLabel(versionLabel); if (itemVersion != null) { relatedDocumentVersionUrl = itemVersion.Url; } } if (string.IsNullOrEmpty(relatedDocumentVersionUrl)) { throw new SPException(string.Format("The '{0}' version of document '{1}' cannot be found. It may have been deleted.", versionLabel, item.Name)); } } return relatedDocumentVersionUrl; } public static Stream OpenBinaryStreamForVersion(this SPFile file, string versionLabel, int? docStoreVersion) { Stream bStream = null; SPFileVersion fileVersion; bool refersToLatestVersion = file.GetFileVersion(versionLabel, out fileVersion, docStoreVersion); if (refersToLatestVersion) { bStream = file.OpenBinaryStream(); } else if (fileVersion != null) { bStream = fileVersion.OpenBinaryStream(); } return bStream; } public static int? GetDocStoreVersion(this SPListItem item) { return GetDocStoreVersion(item.File); } public static int? GetDocStoreVersion(this SPFile file) { int? docStoreVersion = null; if (file != null) { docStoreVersion = (int)file.Properties[Constants.Properties.VTI_DOCSTOREVERSION]; } return docStoreVersion; } public static int? GetDocStoreVersion(this SPFileVersion fileVersion) { int? docStoreVersion = null; if (fileVersion != null) { docStoreVersion = (int)fileVersion.Properties[Constants.Properties.VTI_DOCSTOREVERSION]; } return docStoreVersion; } /// If the fileversion with the provided versionLabel has been promoted via publishing, then we will return the /// fileversion that has been published (that will not have a mathing versionLabel). /// NOTE: This can never return the current version as it is not in the SPFile.Versions collection. /// versionLabel: The version of the document to get /// docStoreVersion: If provided, will get the version using this value (this doesn't change when a version is published), else will attempt to figure it out.</param> /// returns: If the file version is the latest version (need to access the SPFile directly) public static bool GetFileVersion(this SPFile file, string versionLabel, out SPFileVersion fileVersion, int? docStoreVersion = null) { bool refersToLatestVersion = false; fileVersion = null; int docStoreVersionLatest = file.GetDocStoreVersion().Value; if (docStoreVersion.HasValue && docStoreVersion.Value == docStoreVersionLatest) { // The doc store version matches the current version refersToLatestVersion = true; } else if (string.IsNullOrEmpty(versionLabel) || versionLabel == file.UIVersionLabel) { // The version we are looking for matches the current version refersToLatestVersion = true; } else if (docStoreVersionLatest < 3) { // The first doc store version number is 2, therefore it is the only version that there has been refersToLatestVersion = true; } else if (docStoreVersion.HasValue) { // If a doc store version has been provided we can find it in the previous versions fileVersion = file.Versions.Cast<SPFileVersion>().FirstOrDefault(v => v.GetDocStoreVersion() == docStoreVersion.Value); } else { // Get previous version by version label fileVersion = file.Versions.GetVersionFromLabel(versionLabel); if (fileVersion == null) { // We don't have the docstore version to find but if the previous verions docstore version minus the next version docstor version = 1, then it has been published. // Note that this only covers the case where the version gets published, when multiple versions have been deleted this may fail to return a version. // ... I have not included this code for brevity ... } } if (!refersToLatestVersion && fileVersion == null) { string errMsg = "Failed to locate specific file version, URL: {0}, VersionLabel: {1}, DocStoreVersion: {2}"; string docStoreVersionString = docStoreVersion.HasValue ? docStoreVersion.Value.ToString() : "Unspecified"; Log.WriteLog(string.Format(errMsg, file.ServerRelativeUrl, versionLabel, docStoreVersionString), TraceSeverity.High, DiagnosticServiceLogger.LogCategories.GroupsAndProjects); } return refersToLatestVersion; }

Please leave a comment and if you want to keep reading more about SharePoint don’t forget to subscribe.

SharePoint Conference 2012

The annual SharePoint Conference 2012 (SPC) is here and it’s in Las Vegas!

This time around it is particularly big news as SharePoint 2013 RTM was released at the end of last month, not to mention the recent Windows 8 release, the Surface and the acquisition of Yammer. I was lucky enough to be sent to the conference on behalf of Concentra to learn firsthand from those in know including MVPs and Microsoft themselves. It’s not only my first time at the conference but my first time at an event while it’s trending globally on Twitter.

Before coming to Las Vegas I had a few preconceived ideas about what to expect and what I considered to be the greatest improvements with the new version. The new App model was always going to be a highlight and naturally it was the focus of the keynote session. It’s powerful, it’s agile, it’s accessible and I’m really looking forward to getting deep into it. Jeff Teper and Scott Guthrie spent a good portion of the keynote session just on this very topic but equally represented was Yammer. For myself, I was surprised at the amount of attention the Yammer acquisition received. Both David Sacks and Adam Pisoni (Yammer Founder and Co-founder) took the stage and although I wasn’t blown away it looks like SharePoint has a strong future in regards to social especially seeing as most of Yammer now comes for free with SharePoint 2013. It was mentioned that the 3 year software development cycle has come to an end and a new 9 day cycle has begun – so hopefully we can expect more features more often going forward.

I spent the remainder of my day in sessions about the new App model. I plan on writing another blog in the near future that will get technical on the subject so for now I’ll pass over it but will say that it’s looking like a great model and along with the greatly improved RESTful services and Client Side Object Model (CSOM) is really quite exciting. The biggest surprise for me so far: Office Apps are very cool. It is now possible to do anything that can be done in SharePoint (think BI tools like geographically mapping table data or productivity tools that let you turn that table data into a SharePoint list or allows you to search for and reference specification documents) directly via Word, Excel, PowerPoint and Project with a single app (an App will work across the suite unmodified). And because Office Apps are built using the same web technologies as SharePoint Apps, you can make your SharePoint Apps available via Office applications with minimal effort and vice-versa.

There is a lot more to come with over 300 sessions being presented. There is at least three sessions I’d like to see for each and every time slot and it is tough work choosing the best track. I missed out on what I heard was a great session on search but thankfully there are plenty more. Search is destined to be another highlight of the conference as a lot of work has been done empowering both information users and developers to create more relevant solutions more easily. With well over 10,000 attendees here it is also a great opportunity to network – I was lucky enough to take a helicopter tour over the Grand Canyon with none other than MVP Chris O’Brien.

Look out for more blogs in the near future about all the new SharePoint goodness in greater detail.

Visual Studio Developer Tips

Visual Studio is an excellent IDE for working with Microsoft technologies. However, it isn’t perfect and can crash or hang from time to time. After experiencing an issue with the IDE during a debugging session recently, I came across a setting which improved my Visual Studio experience and thought it was time to bring together some of my favourite tips.

1. Navigate To (CTRL+COMMA)

This outstanding useful key combination brings up the ‘Navigate To’ dialog which allows you to find almost anything -files, classes, methods, properties. It is so easy and so fast that, IMO, it should be used instead of the Solution Explorer whenever you know the name of anything you are looking for.

2. Debug > Delete All Breakpoints (CTRL+SHIFT+F9)

Regularly deleting all breakpoints can greatly improve you debugging experience within VS. The performance impact upon attaching to a process per of individual breakpoint is negligible. However, after some time, presumably accelerated by merging from source control, the solution can become corrupt (I use the term ‘corrupt’ tentatively because the solution is still functional) such that loading symbols upon attaching to a process can take an exceptionally long time. Deleting all breakpoints (using the command, not individually) refreshes all references and fixes this issue.

3. Solution Explorer Collapse And Sync (Solution Explorer Tools in VS2010)

Installing this VS add-on provides what can be very useful macros for the solution explorer depending on how you use it. It provides functionality such as ‘close all branches’ and ‘open to the current branch’.

The Solution Explorer Tools toolbar

You can find it here.

Personally, I quite like the built-in ‘Tools > Options > Projects and Solutions > General > Track Active Item In Solution Explorer’ which ensures that the solution explorer is always open to currently active file, but I know a lot of users will hate the way it jumps about.

4. Dark Themes

Even with relatively fresh young eyes, staring at a white screen is painful after a few long sessions. Bring on the dark themes. Using a theme with a dark grey background saves my eyes and keeps me in the zone! There are many great ones and a handy designer for creating your own. With the release of VS2012 there is now even greater granular semantic colourisation.

5. Deactivate Implicit Property Evaluation

Tools > Options > Debugging > General > (uncheck) “Enable property evaluation and other implicit function calls”

The impact of this is that properties aren’t evaluated unless you inspect them individually (explicitly). This means that you can no longer view all properties on an object by calling it in the immediate window – you have to inspect properties one-by-one. As SharePoint objects have dozens of properties this can make a noticeable difference when debugging SharePoint code. As such, your mileage may vary depending on what you are debugging and the relative performance of your debugging environment.

6. Integrate Third Party Diff Tool

You can swap in external programs to perform your file merging and file diffing activities. Personally, I think that WinMerge is fantastic, especially after fine tuning the comparison settings (e.g. skip white space, block detection, etc.), but whatever you find is your favourite utility for these actions it almost certainly isn’t the default. Paul Bouwer has already blogged in detail about how to plug it in:

These are tips that I expect to be useful for nearly any developer working with Visual Studio. Depending on what you are working on it is always worth a quick web search to see what else is out there to aid your efforts and help you work smarter.

With Windows 8 and SharePoint Apps being a development focus, the web development improvements in VS2012 will be obvious. It also includes SharePoint asset designers, a SharePoint profiler and more built in SharePoint templates among many other features.