If you are a C# developer that is new to Powershell, or at least new to writing Powershell functions with typed parameters you will likely come across the following error:
Cannot convert the "System.Object[]" value of type "System.Object[]" to type "<type of first argument>"
The reason for this error is most likely because you are passing a comma separated list of arguments as you would in C#:
myfunction arg1, arg2, arg3 or perhaps even myfunction(arg1, arg2, arg3)
In both of these cases you are in fact passing an array of objects as the single and only parameter. Considering this, the error message makes perfect sense. In Powershell the comma is an array operator (see here) and arguments should be passed to a function delimited only by a space character. Like so:
myfunction arg1 arg2 arg3
This brings up another question though: “how come I wasn’t getting an error when I had untyped parameters (or string type parameters)?”
This is because under the covers the arguments list is just an object array and the parameters are positional – they retrieved by indexing into the arguments array. When you are passing a single parameter that is an object array you are passing in the arguments array itself. When the parameters are typed such that they can be auto-converted from an object type (eg string) then it will work as expected.
There is a web.config file under the _layouts folder. This is worth being aware of as you may notice that files that you access from the _layouts folder may not behave as you would expect. This came to my attention when I was getting the following error:
”To enable the details of this specific error message to be viewable on remote machines, please create a tag within a “web.config” configuration file located in the root directory of the current web application. This tag should then have its “mode” attribute set to “Off”.
This initially surprised me as I knew that I had already done as such and had recently seen the default error screens when I was building web parts on content pages.
As the web.config under the layouts folder is deeper in the site hierarchy, any elements defined here will overwrite those defined at the web application level. By default the customErrors element exists at this level and it must be set accordingly to your needs as well.
As always, be careful when editing web.config files and always make a backup beforehand.
After attending the SharePoint Conference a couple of weeks ago in Las Vegas I was inspired to spend some time with Office Apps. Office Apps allow you to show a web page within an Office program. Literally, it is as basic as an iFrame within Word (or Excel etc) and a JavaScript library that provides an API into Office. An xml manifest file defines the app web URL and the permissions the app requires (plus some other settings) and is the only thing that the client application is required to install.
The Anatomy of an Office App – Thanks to Microsoft for the image
I’ll start with a quick overview in case you aren’t aware of what’s possible. I use the term ‘document’ generically to refer to any Office file type (docx, pptx, xlsx) unless I specify otherwise.
Office App Shapes
Office Apps come in three distinct ‘shapes’ (this is Microsoft’s term, read: types).
Task Pane: This app shape is housed in a panel outside of the document. Think of the ‘Solution Explorer’ in Visual Studio. You can influence the document via the app but the app doesn’t constitute part of the document itself. This shape is very flexible; it can run in any of Word, PowerPoint, Excel and Project. That is; the exact same app can be published for use in any of these programs, unmodified. You will have to consider the programs you decide to support as there are some discrepancies that will need to be taken into account. An example of this is the DocumentSelectionChanged event which fires upon each key stroke in Word but only upon changing cell selection in Excel. I imagine that this will be the most common app shape as it can provide powerful tools to help a user create/modify/research a document or complete related tasks without opening your browser in order to visit SharePoint
A Task Pane App – Thanks to Microsoft for the image
Content: This app shape sits ‘in’ the document, as part of the content. Think of a chart in Excel. In fact, if you had a desire to reinvent the wheel, you could create a content app that replicates chart functionally. Currently, content apps are only supported in Excel but this only a temporary limitation (during the conference sessions Microsoft made a point of this on multiple occasions). Content apps can provide an easy way to share content (you can email them!) or bring dynamic content into documents. Perhaps this shape could be used to create powerful dynamic coversheets with a lot more pizazz than Quick Parts provide.
A Content App – Thanks to Microsoft for the image
Mail: This app shape is very similar to the Task Pane shape except that it is for Outlook. It also provides a pretty cool visibility model where you are able to define rules (e.g. is the item a message or an event) which when satisfied makes the app appear. I’m not going to cover this app shape in more depth specifically, however the flexible nature of Office Apps means that the concepts I do cover will be transferable in most cases.
A Mail App – Thanks to Microsoft for the image
Environment
In order to start to developing Office Apps you require Visual Studio 2012 (Express is fine) with Microsoft Office Developer Tool for Visual Studio 2012 and Office 2013. I was only using Office 2013 Preview and was able to develop apps fine with a couple of caveats. Firstly, the API is slightly different between versions (you should be using a different version of office.js and I assume the gap will only get greater as the API matures). An example of this is trying to read the current document – you have to use a different method for Preview. Secondly, I couldn’t debug my apps in Visual Studio. I’m not sure if I’m overlooking something or whether it’s a limitation of using Office Preview. I will edit this blog when I have a chance to investigate this issue fully. I should also mention that you need IE9+ installed although it needn’t be your default browser.
Starting a New Project
The ‘App for Office 2013’ Visual Studio template goes a long way to getting you started. Start a new project: File > New > Project, then Installed > Templates > Visual C# > Office/SharePoint > App for Office 2013. If you know you want to create a Task Pane App of Content App then select accordingly but in either case it is very simple to convert one to the other, you just have to make a few small modifications to the manifest xml file.
Converting App Shapes
The xsi:type parameter can be ‘TaskPaneApp’ or ‘ContentApp’ accordingly, Task Pane Apps don’t support the RequestedWidth or RequestedHeight elements and lastly (and temporarily) Content Apps only support the Capability element when its Name attribute is ‘Workbook’.
Limitations
You can’t draw iFrames in Office Apps. At first I thought this wasn’t an issue, but it does mean that you can’t just host some related SharePoint content in an app, you have to go to the effort of getting the content via a web service (possibly having to write the web service) and then handle rendering it.
You can’t change the document from the app. You can read, write and close the document but you can’t open another document. I can imagine (and really hope) that this may change in the future as it could allow users who spend a lot of time modifying documents to switch between documents hosted in a range of sites without leaving Office.
You can’t pass arguments to Office Apps. I had hoped that it would be possible to provide a URL that would launch a document, insert a specified app (or prompt to install it), and initiate the app with some provided data. Unfortunately it can’t be done (yet?).
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.
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:
Please leave a comment and if you want to keep reading more about SharePoint don’t forget to subscribe.
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.
The “Navigate To…” dialog
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’.
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.
“Son of Obsidian” from StudioStyles
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:
WinMerge in action
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.
