The Right Way to Version Your Assemblies

No, I'm not talking about whether you have Major, Minor, Patch, and Build numbers.  I'm not talking about when you increment which number.  My suggestion is to do whatever works for you in those cases, though I reserve the right to blog about that in the future.
What I am talking about is how you can structure your solution and project files in Visual Studio to make updating your assemblies' version number much easier.
This blog post makes some assumptions:

• You are using version numbers in your assemblies
• You are using a recent version of Visual Studio (I know these steps work with both Visual Studio 2008 and 2010)
• You have multiple assemblies in one Visual Studio solution
• You want to update all of your assemblies' version numbers at the same time and to the same version number

Those assumptions cover a vast majority of the projects I've worked on, but I'll admit that there may be projects out there that might not fit into the mold I've set forth.  I'm OK with that.  This blog post isn't for you if your mold is different.
So let's get started.
I created a solution file which contains several projects.  There's an MVC2 web application project, its associated test project, a business objects project, and a data access layer project.  These are all empty projects for this example—only the structure of the solution and projects is important for my purposes.  Solution explorer for this project is shown here.
The first step is to separate out the version information (and any other information that is common from assembly to assembly if you wish, like company name, product name, and so on) into its own file.  Open up one of the AssemblyInfo.cs files to see what I'm talking about.

Notice that the settings are assembly attributes.  Some people don't realize that you don't have to put all the assembly attributes in one file.  I'm going to take advantage of that fact to accomplish what I set out to do: change the version in one place and have all projects updated at once.  The other key is using a solution-level file and linking to is from each project.
Visual Studio supports files at the solution level as well as at the project level.  You can put anything you want at the solution level and it will be carried along with the solution, though it won't get included in any output unless you write some custom build rules to grab the file and do something with it.  On some projects I've included a Word document about the solution and its projects as a solution level file.
For this example, we're going to create a new C# source file and include it at the solution level.  I'm going to call this new file, "VersionInfo.cs".
Step 1: Create a new file and call it "VersionInfo.cs".  Do this by choosing "File | New | File…" or press Ctrl-N in Visual Studio.  Choose "Visual C# Class" as the file type.
Step 2: Erase everything in this file.  Save it as VersionInfo.cs in the same folder as the solution file.
Step 3: Highlight the version information lines from the AssemblyInfo.cs file from earlier, cut it from that file (Ctrl-X) and paste it in VersionInfo.cs (Ctrl-V).  Add "using System.Reflection;" to the top of VersionInfo.cs to avoid compilation errors.
Step 4: Add the VersionInfo.cs file to the solution by right-clicking on the solution file, choosing "Add | Existing Item…", then selecting "VersionInfo.cs" (find it in the solution's folder where you just saved it), and then click "Add".  You should see a new "Solution Items" folder under your solution name with the VersionInfo.cs file in it (see screenshot).
Step 5: Add the VersionInfo.cs file to each project as a linked file. See below for instructions on how to do this.
Step 6: Remove the version information from the other projects' AssemblyInfo.cs files.
At this point you should be able to build your solution successfully, and each assembly should have the same version information—the information found in VersionInfo.cs.
So what is a "Linked File" and how do I create one?  Read on.
Right-click on the project and choose "Add | Existing Item…", navigate up one folder level, and click once (don't double-click!) on the VersionInfo.cs file.  [This assumes that your solution folder is one level up from your project folder!]  Now instead of clicking "Add", click the little down-arrow next to the "Add" button.  Choose "Add As Link".  You should now see VersionInfo.cs in your project, but with a "shortcut" icon overlaid on top of the file's icon.
Once you have completed this step for each project, you can build your solution without errors.
Now to test it out.  Build the solution and look in the bin folder (or "folders" if you haven't added the other projects as references in the web project) for the DLLs.  Look at the version numbers.  They should all read "1.0.0.0".
Now change the version number in the VersionInfo.cs file information.  Rebuild the solution then check the version numbers.  All of the assemblies should now have the new version number.
Notice, however, that it is the "File Version" that you see when hovering over the DLL in Windows Explorer, so if you change only the "Assembly Version" the you'll have to go to the DLL's properties to see your change.
[I must admit, I don't recall which version number is used when putting DLLs into the Global Assembly Cache.  Please leave a comment if you have that information handy!]
So that is the procedure.  If you have an automated build system then you can make use of the fact that the version number is in its own file and update it automatically.  Then each build will produce DLLs with distinct version numbers.  That is a great way to identify the build that a DLL came from if you happen to get a report from the field that there is an error in a specific DLL.
But I'm sure that's never happened to you…right?
[Update: adding to CodeProject]

Completely Empty the SharePoint Recycle Bin

If you have LOTS of stuff in your SharePoint Recycle Bin and want to empty it all, here’s a quick tip:

1. Navigate to the recycle bin page (e.g. http://localhost/_layouts/recyclebin.aspx)

2. In the address bar, type “javascript:emptyItems()” (minus the quotes)

3. Press enter. You will be asked if you really want to empty the recycle bin.

4. Click OK to empty it; click Cancel to leave it alone.

It’s much faster to empty it this way if you have multiple pages of “stuff” in your recycle bin.

Error While Refreshing External Data Source in Excel

I have an Excel 2007 workbook that pulls its data from an Access 2007 database to give users some feedback via charts and graphs.  [For this discussion it doesn't matter that Access actually gets the data via links to lists on a SharePoint site—the error I encountered deals with the connection between Excel and Access.]

I added an "Update" button that the user presses to ensure that all of the data is freshly pulled from Access.  Initially I just called

ThisWorkbook.RefreshAll

However, I received an error at some point that I couldn't pinpoint.  I have about 150 different queries that pull data from Access, and trying to find the one query that was failing was like finding the proverbial needle in a haystack.

So I changed the code to loop though all of the named ranges in the workbook.  I had given all of the data tables names when developing the spreadsheet, and so the new code looks like:

for each name in ThisWorkbook.Names
   name.RefersToRange.ListObject.QueryTable.Refresh
next

[Yes, I check for whether the name object actually refers to a range, and if so, whether that range has a List Object, and if so, whether that List Object has a Query Table to refresh!]

This way I could tell which range was being refreshed and could inform the developer (me) of which range was causing the problem. I could also calculate a percent complete value to display on the status bar, since I knew how many names there were and which name I was currently working on (via a "currentName" variable).

This looked promising, but I again got an error.  Looking at the named range that the code was refreshing when the error occurred, I didn't see anything wrong with it.  I could manually refresh it with no problem.

So I started looking at the properties of the QueryTable object to see if there were any clues in there.  That's when I stumbled upon the "MaintainConnection" property.

I changed the code to this, to see if it made any difference:

for each n in ThisWorkbook.Names
n.RefersToRange.ListObject.QueryTable.MaintainConnection = False
n.RefersToRange.ListObject.QueryTable.Refresh
next

This time when I ran it, it ran to completion without any errors.

So it seems that if you try to maintain your connection to the database, you'll eventually run out of available connections.  What's strange is that the searches I did came up with information about Excel handling up to 255 connections, and I seemed to bump into this problem at about connection number 60 or so.  I'm not sure of the exact count—it could have been more or less than 60, but it was pretty close, I believe.

So if you're attempting this on your own, take it from me: set the MaintainConnection property to False!

Don't Forget to "DoEvents"

I'm writing a reporting package which uses Microsoft Access and Microsoft Excel to gather and chart data collected from a set of custom SharePoint lists.  I have some VBA code which does some calculations on all of the list items before the reports are generated to ensure that the data is the most up-to-date that it can be.

The VBA code lives in Access.  It basically does a lookup on each row in one of my lists and sets values in another list.  The business rules for this update had enough conditions on it that I couldn't implement it in one complex Update statement, thus the looping.

I also discovered that you can very easily add a progress bar to the Access status bar by calling "SysCmd acSysCmdInitMeter, 'message', maximum value" to initialize it, and "SysCmd acSysCmdUpdateMeter, currentValue" to increment the counter.  (To reset the status bar when I'm done, I call "SysCmd acSysCmdRemoveMeter".)  So I added this bit of functionality to the VBA code as a bonus for my users to give them some feedback.  After all, some of the lists I'm working with have a few thousand items in them (don't get me started about best practices stating that 2000 items is the workable maximum—I've already fought that battle and lost!) and it can take some time for the VBA code to complete.

Well wouldn't you know it, but the update code continually ran, and the thread blocked on the SQL command, so the progress bar just sat there, no progressing.  Furthermore, the whole UI appeared to be locked up while the update was running.  I couldn't even pause execution of the VBA code because the IDE wouldn't recognize my mouse clicks on the pause button.

And then I remembered something from my old VB6 days: the DoEvents method.

The DoEvents method relinquishes control of the processor by the VBA engine to allow other processes to do things. Or more accurately in my case, other threads. It was more important to call it when a background thread was doing heavy processing and you wanted to allow the UI thread a chance to handle the mouse clicks, keyboard presses, and other events which had queued up since the last time it got a time slice from the operating system.

I remembered one main warning about using it, though:

• You don't want to call it too often, since an expensive context switch most likely would take place

So I decided to see if it worked in VBA by adding this block of code:

If currentRow Mod 10 = 0 Then
    DoEvents
End If

In this block of code, currentRow is an integer which gets incremented each time through the loop. It is the variable that I pass to the method which updates the progress bar. You can see that I don't call DoEvents each time through the loop—I want the main processing code to actually finish in a reasonable amount of time, after all!

The IDE didn't complain about the method call, so it at least recognized it as valid VBA code.  So far, so good. But will it accomplish what I want it to?

The short answer: YES!

So now, in the latest version of the code, the DoEvents method is called every 10 rows.  This allows the UI to get refreshed, so I can now pause execution and scroll through the source code (albeit in bursts).

But more importantly, the progress bar now shows progress as the code runs!

DoEvents FTW!

Best Practices for Building SharePoint Solutions

A friend forwarded this link to me: 10 Best Practices For Building SharePoint Solutions.  Most are fairly obvious, but sometimes it's good to state the obvious things, lest we forget them.

Performing Outer Joins on a SharePoint List from Access

I'm currently creating reports from the custom SharePoint lists I have been working on over the past few months.  The way I'm accessing the data in my SharePoint lists is through Access 2007, and then I have an Excel 2007 spreadsheet which uses the Access database to get the data. In this manner, I can use the power of Access' database engine to perform queries against my lists, and then just import the data to Excel.  It sounds cumbersome, and perhaps I'm showing some of my ignorance of Access and Excel development, but it runs much faster than the earlier version of the report which uses VBA only to generate similar reports.

That being said, I ran into an issue with one query.  I have a list which tracks FCC filings.  There can be a major filing and a minor filing, both tied to the same physical location.  So there can be one or two filings (items) per location stored in this list.  I needed to report on whether the filings were "complete".  They are considered complete if the major filing is complete, or if the minor filing is complete in the case where a location does not have a major filing.

My SQL statement was structured like this:

SELECT * FROM
(
    SELECT <<completed major filings>>
    FROM Filings
    WHERE Filings.Type = 'Major'
UNION
    SELECT <<completed minor filings>>
    FROM Filings Minor
    LEFT JOIN Filings Major ON Minor.Location = Major.Location
    WHERE Minor.Type = 'Minor'
    AND Major.Type = 'Major'
)

However, this didn't work.  The second part of the query kept behaving like an inner join.  I did some proofs-of-concept to discover that, yes, outer joins do work in Access on actual tables within Access, but they just weren't working on linked tables where the source is SharePoint.

What to do?

After beating my head against the wall for a while, and possibly pulling some hair out, I finally had the bright idea to break things into smaller chunks.  Thinking that Access had a problem joining a linked table with itself, I created an Access query which only returned items representing minor filings, and another Access query which only returned items representing major filings.  Then I removed the where clauses from my original SQL statement above and replaced direct access to the linked table with the queries I had created.

It worked beautifully!

The new SQL Statement looks like this:

SELECT * FROM
(
    SELECT <<completed major filings>>
    FROM AllMajorFilings
UNION
    SELECT <<completed minor filings>>
    FROM AllMinorFilings Minor
    LEFT JOIN AllMajorFilings Major ON Minor.Location = Major.Location
)

Lesson learned: when working with Access, break things into smaller components to avoid confusing Access.

I can't wait to get back to "normal" C# development!

Strange Column Names

In SharePoint 2007, you can have a column named "!".

I'm sure there are other characters you can use, as well, but this one surprised me. I suppose it is because I'm a C# developer…the "!" (or "bang") is an operator, not an identifier.

But in SharePoint (at least the 2007 version) it is a valid column name.

[Update: It appears that the column named "!" appears in SharePoint Designer as "_". I haven't tried including this column in any of my workflows, so I'm not sure how it would behave. If you have the opportunity to do so, please leave a note letting me know how it works for you. -sj]

SharePoint “Lookup” Columns

As you may know, you can include a “Lookup” column in your SharePoint 2007 lists which, in effect, creates a reference to another SharePoint list.  This can be used, for example, if you have an address list and want to ensure that your states or provinces are all spelled correctly—just create a “StatesProvinces” list, fill it with the properly-named states and provinces, then add a reference to it in your address list. The user experience is a combo box containing the items in the “StatesProvinces” list, and they can select the one they want without having to type it themselves. [Note that you can configure SharePoint to allow multiple items from the referenced list to be selected, but that’s not what I’m focusing on in this post.]

In order to add a lookup column to your list, you first must have created the other list that you are going to reference.  You don’t actually need data in it, yet, but it does need to be created.  Fair enough.

Next, after choosing the list, you must choose which column in that other list you want to display to the user.  So in this example, you may want to have the “Title” column display to the user.

Once you save everything and add data to the “StatesProvinces” list, you have a workable solution.

But what if you want to have a workflow run against this address list which has the reference to the “StatesProvinces” list?  This is where you need to know a little bit about the inner workings of lookup columns in SharePoint.

If you know anything about database development, you probably know about the concept of a “foreign key”. In short, a foreign key resides in a table that is related to another table.  Let’s call the first table the “Child” table, and the second table the “Parent” table.  So the Child table would hold the foreign key to the Parent table.

What does a foreign key look like? Simple: it is the primary key of the Parent. [A primary key uniquely identifies a row in the database table.] It is usually a numeric type.

The same concept applies to a lookup column in SharePoint, but the execution is slightly different. You see, the actual value stored in the lookup column is the ID of the referenced list, but what is displayed to the user is the configured column from that list.

Back to my workflow scenario: if you want to manipulate lookup columns from a SharePoint workflow, and I’m talking specifically about using SharePoint Designer to create the workflows, you need to keep the foreign key concept in mind. As a test of this, do the following:

1. Create a workflow and attach it to a SharePoint list which contains a lookup column.
2. Create two variables in the workflow, one of type “String” and one of type “List Item ID”.
3. Set both variables to the value of the lookup column

If you examine the contents of each variable (by logging it to the workflow history) you will see that the String variable contains the value of the configured column to display (in our example, the “Title” column), and the List Item ID variable would have a number (which corresponds to the ID column of the referenced list).

If you are going to change the value in the Lookup column via a workflow, you must set its List Item ID (number), not the displayed value(text).  You will wonder why your workflow isn’t working correctly if you don’t follow this advice, especially if you are new to creating SharePoint workflows using SharePoint Designer.

I hope I have helped someone out there with this advice.

How Can You Tell if You Found a Valid List ID?

I’m currently working with several different custom SharePoint lists.  Some of the lists have references to other lists, via a “Lookup” column.  For example, a book might have a reference back to the library it came from.

Sometimes I only know the name of the library, and I want to be able to set a reference to it on the book’s list.  So I retrieve the library’s ID using the name of the library.  SharePoint Designer dutifully warns me that I’m not looking up the value using a unique ID, and that it will just give me the first one it finds.  I’m OK with that, since I control the names and I know that they’re all unique.

But I’m only human, and sometimes I don’t have a library name that exists in my library list.

In those cases, when I log the contents of the list ID variable into which I placed the data, it shows me “0”.  [That’s the number zero, not to be confused with a lower-case “o”.  I’m considering changing the font for this blog… -sj]

As it turns out, this is the way you can tell if you have a valid list ID.  Valid IDs start at 1, I presume, and invalid IDs are all zero.

[It’s easy to tell if you have a bad reference to another list when you retrieve string values, since they show up in log messages as “????”.]

Workflow Comparisons Aren’t Always Accurate

I have a SharePoint workflow, developed with SharePoint Designer, which is supposed to compare values in the list it is attached to against values in another list, and copy the other list’s values if they are different.  I kept noticing, via a workflow history log message, that the workflow was copying values every time it ran, even though in another log message for the same workflow instance it showed me that all the values were the same.

As it turned out, I was comparing a string value to a list ID.  Even though they both printed in the log message exactly the same (and so were “equal” in my eyes), SharePoint saw them as different values.

The fix was to copy the list ID value to a string variable, and then compare the two values as strings.

[As a side note, what made this worse was that I had a second workflow which would run when anything was changed on the list.  It would then update a value in the list, which would then cause the buggy workflow described above to run again.  For the astute readers, this meant that the two workflows attached to the same list would cause each other to run infinitely.  It pretty much brought the site to a halt!]

SharePoint Permission Tip

If you use the “Collect Information from User” action in a SharePoint Designer workflow, and you have your default site permissions set only to “read” for the user you’re planning on collecting information from, you probably won’t get very far.

You’ll want to grant at least “Edit” permission to the user (or group that the user is in—that would be a better practice) on the Task list.  This allows the user to access the task that gets assigned to her so that she can complete her work.

Here’s how to accomplish this:

1. Click on the “Tasks” list on the Quick Launch pane if it is available.  Otherwise, click on “Lists” first, and then click on the “Tasks” list.
2. Click on “Settings | List Settings”
3. Click on “Permissions for this list”
4. Click on “Actions | Edit Permissions”
5. Click “OK” on the resulting dialog box (“You are about to create unique permissions for this list…”)

Now you can modify the permissions for the users and groups listed.  If you don’t see the users or groups you want to configure for the Tasks list, you can add them here.

I must note that I created more granular permission levels on the site I’m currently working on, so I can choose to grant “Read” access or “Edit” access individually.  If you only have the out of the box permission levels, you’ll want to ensure that your users have at least “Contribute” access to the list. Of course, if you only have the out-of-the-box permission levels and you haven’t created custom levels then you wouldn’t have the problem I had which prompted me to write this post.

I’ll cover creating custom permission levels in a future post.

del.icio.us Tags: sharepoint,tip,permission level,tasks