Remarks

This property returns only a subset of the metadata for a Web site. To get all the metadata, use the AllProperties property.

Huh. So why does it return only a subset? What subset does it return, a random selection perhaps? If it only returns a subset, shouldn’t they have named it SomeProperties or perhaps NotAllProperties instead?

The MSDN docs din’t explain anything, but Google always knows the answer. It turns out that  the Properties property (besides having a confusing name) represents an older mechanism for storing metadata. It has been replaced by the newer AllProperties property, but is still present for backwards compatibility.

Properties returns a SPPropertyBag object, a custom type which can store key/value pairs — keys are case insensitive and are converted to lowercase when added. AllProperties on the other hand uses a standard Hashtable collection to store its key/value pairs and has case sensitive keys. Furthermore, the SPPropertyBag class has its own Update method which updates the database with any changes to the collection. The AllProperties collection on the other hand is  saved by calling the Update method of the SPWeb object.

To add to the confusion, keys added to Properties are also stored in AllProperties, but not the other way around. This explains the “returns only a subset of the metadata” part of the property description.

But it doesn’t stop there — no, joy of joys, there’s more! In SharePoint 2010, four new methods were added to the SPWeb class.

Thanks, that’s so very helpful. Four new methods that deal with SPWeb metadata, and no description or explanation. Which collection do they store their data in? Properties? AllProperties? Both? Their own, separate collection?

Thankfully PowerShell, which I’m just learning to use, allowed me to quickly test the behaviour of the new methods. Perhaps not unexpectedly, they read and write to AllProperties, the more recent of the metadata collections.

It seems like all this has the potential to cause great confusion if not all developers on a team use the same collection to store their metadata. Especially the way Properties updates AllProperties but not vice versa, and the fact that the new methods are not documented, nor is the distinction between Properties and AllProperties explained properly. Luckily though, as I have just recently started to work with SharePoint, this issue hasn’t had the chance to cause me any grief yet… on the contrary, the process discovering all of this on a Friday afternoon proved to be a great source of entertainment.

In addition to enabling more advanced deployment scenarios, this allows you to use the same scripts when you deploy locally and to your test and production environments. The Visual Studio deployment engine is great – but it’s almost too helpful. It cleans up everything for you, automatically fixing all kinds of deployment conflicts.

This creates an artificial environment. In test or production, it’s possible that you never want to actually retract and reinstall your solution, just update it, and if you do reinstall it, Visual Studio is not around to fix deployment conflicts for you. So you may be headed for a nasty surprise when you take your solution to a test server for the first time, and discover there are all sorts of upgrade scenarios to consider.  (For instance, it’s really difficult to overwrite existing files.)

If you use a PowerShell script to deploy from Visual Studio, you can use that same script in development, test and production. This makes your development environment more like real life, which is a Good Thing. And as I showed earlier, you can use different build configurations to choose between different deployment scenarios: Full reinstall, upgrade from previous version, etc.

But there are some stumbling blocks you may encounter once you leave the safe world of the Visual Studio deployment engine. I mentioned one earlier – getting your PowerShell scripts to run in 64-bit mode – and here’s another: The Global Assembly Cache.

Let’s say you’ve added a new feature and a new feature receiver to your solution, and you deploy it with a PowerShell script. You may experience that the feature can not be installed, because the receiver class couldn’t be found. Or you’ve changed the code in a feature receiver, and you experience that the old code is executed instead of a new one when you deploy.

Why? Because when a process loads an assembly from the Global Assembly Cache, it will keep using that version of the assembly for the rest of its life even if a new version has later been added to the GAC. Solution deployment is run by the SharePoint 2010 Timer service, and features are activated within your PowerShell process. So if something you’ve done earlier has caused one of these processes to load the assemblies you’re updating, an old version of your code will be used during solution deployment or feature activation.

The solution is to restart the timer service, and launch new PowerShell processes, whenever you require the latest version of an assembly to run.

(Update: The timer service problem described here happens when you retract a solution, then reinstall it with a new feature receiver, or a feature receiver with a changed name. The problem does not occur when you update an already installed solution.  You still have to launch a new PowerShell process, though.)

To restart the timer service, run this:

restart-service SPTimerV4

And to launch a new PowerShell process, just call PowerShell from your script like this:

$scriptPath = split-path $myInvocation.MyCommand.Definition

powershell -file (join-path $scriptPath Retract-Solution.ps1) -solutionId $solutionId -url $url -package $package

powershell -file (join-path $scriptPath Install-Solution.ps1) -solutionId $solutionId -url $url -package $package

In this example I have one script that retracts a solution, and another that installs it.  Each is launched in a separate process, ensuring that they’ll get a fresh copy of the solution assemblies, and before they install/uninstall the solutions, they restart the timer service.

(There may be other processes to consider in other scenarios – check the SharePoint logs to see which process is performing which operations.)

Why isn’t this a problem when you do Visual Studio deployment?  Actually I have encountered that problem with Visual Studio, and had to restart it, but that may have been a bug in the beta.  In any case, Visual Studio runs its deployment steps with a process called vssphost4, which works directly with the object model, not through the Timer service.  So it takes care of this for you.

In other words, the Visual Studio deployment engine is really helpful when you’re getting started with SharePoint 2010, but not something you don’t want to rely on too much later on. If you develop SharePoint solutions, you have to face difficult deployment issues at some point.  Better that you face them on your development machine than on a production server.

The configuration options are fairly limited.  For instance, you can choose to “activate features” as part of the deployment.  But what if you have multiple features in your solution, and you normally only want to activate some of them?  You could move the rest into their own solution, but that’s an ugly way to solve this.  What then?

There are some guides on the web about how to make your own custom deployment steps, which can then do things like only activate some features instead of all of them.  Here’s a series of posts by Eric Shupps – part one, two, three.  This is interesting, but it’s a lot of components to make for what could really be just a simple deployment script.  And then if you want to change the deployment step later, you’ll have to update the extension you’ve made on all the Visual Studio installations in your team.

What I prefer instead is to extend the deployment steps with PowerShell scripts.  You can of course run PowerShell scripts whenever you like outside of Visual Studio, but running them as part of the Visual Studio deployment steps is much more convenient.  You build, the scripts run, and there you are.  Here’s how to do it.

Launching a PowerShell script during deployment

The first thing you’ll want to do is create a new deployment configuration in the SharePoint tab in the project properties, and configure it to do nothing except run the post-deployment command line.

Next, create a PowerShell script file and put it in your project.  You could also put it somewhere else, since it isn’t strictly a part of the solution, but it’s more convenient that way.

Finally, add something like this to your Post-deployment Command Line:

%windir%\sysnative\windowspowershell\v1.0\powershell -file “$(ProjectDir)\Scripts\Deploy-Solution.ps1″ -configuration “$(ConfigurationName)” -url “$(SharePointSiteUrl)” -package “$(TargetDir)$(TargetName).wsp”

The sysnative part at the beginning is necessary in order to launch PowerShell as a 64-bit process.  Visual Studio 2010 is 32-bit, and when you start PowerShell (or any other system command) from a 32-bit process, it automatically launches the 32-bit version of that tool.  This will fail, because SharePoint 2010 is 64-bit only.

On a 64-bit Windows machine, the 32-bit versions of system tools are located in c:\windows\SysWOW64, and the 64-bit versions in c:\windows\system32, (which is confusing enough in itself), but even if you explicitly refer to an application in system32, you’ll get the 32-bit version from SysWOW64 instead, because of magic.  %windir%\sysnative overrides that magic.  The sysnative folder only exists when you’re running in a 32-bit process, so don’t go looking for it on the disk, but it will be there when Visual Studio runs the post-deployment command line.

Btw: There is also a Visual Studio extension from Imtech that allows you to run a PowerShell script as a deployment step.  This is a good idea, and would accomplish the same thing, but I couldn’t get it to work on Visual Studio 2010 RC, so it probably needs some more work.

Supporting multiple configurations

What’s all those input parameters?  You don’t need to have them there, but they illustrate how you can integrate your script with the build variables from Visual Studio, which opens up some really exciting possibilities.

$(ConfigurationName) is the name of the active configuration, such as Debug or Release.  $(SharePointSiteUrl) is the URL you’ve selected in the properties of the SharePoint project.  And $(TargetDir)$(TargetName).wsp is the name of the solution package file.

Some of these variables are the same as those you see in the pre- and post-build event editor.  SharePointSiteUrl is an extra variable that is available for SharePoint projects.  There are more, and they’re listed here.

In order to read these parameters in your script, add this line at the top:

Param($configuration, $url, $package)

Here’s the fun part: Your script can now test on the active configuration, and change the deployment accordingly.  For instance, you could have one configuration that retracts and installs the solution, another that upgrades an existing solution, and one that just adds your assemblies directly to the GAC, (in order to save time when all you’ve done is change code).

You’ll also want to add the SharePoint snapin:

$snapin = get-pssnapin | where { $_.Name -eq “Microsoft.SharePoint.PowerShell” }

if($snapin -eq $null)  {

Add-PsSnapin Microsoft.SharePoint.PowerShell

}

By testing on whether the snapin is already loaded, you can also run this script from the SharePoint management shell.

This is a good starting point for taking full control of your Visual Studio deployment.  No need to create Visual Studio extensions, just do everything in PowerShell.

(Update: Also read this entry about avoiding assembly cache problems during deployment.)

(Previously the terms unghosted and ghosted were used instead of customized and uncustomized.  This was confusing, and you should forget them right away.)

When files are uncustomized, multiple sites may be using the same copy of the file, so you can change it in one place, without having to update every single instance of it in different sites.  If the files are ASPX pages or master pages, there’s another advantage to having them uncustomized: Customized pages have a lot of restrictions.  For instance,  you can’t have inline code or use sessions without adding an exception for your page in the PageParserPaths section of web.config.   The reason is that, otherwise, users of a site could just upload some code and have it executed, which would be a gaping security hole.

Normally you add uncustomized pages through features, using the File element.  But there’s a drawback: If the page exists already, for instance because you’re trying to replace a standard page like default.aspx, there appears to be no way to overwrite the existing file.  The documentation implies that you can do this with the IgnoreIfAlreadyExists attribute, but that’s not actually the case.  IgnoreIfAlreadyExists just determines whether SharePoint should let you know (by failing to activate the feature) that it couldn’t overwrite the existing file.

The only way to overwrite a file as part of a feature activation is to do it programmatically, in the feature receiver’s FeatureActivated event, (and/or delete the file in FeatureDeactivated).  Here’s a good description of how to add a file by parsing the feature definition and adding the SPFile objects in code.  But this example won’t work if you want to add an uncustomized file.

There actually seems to be no way to create an uncustomized file through the SharePoint object model.  There is a method called AddGhosted in the internal SPRequest class, but using SPRequest to bypass the public API leaves your installation in an unsupported state, which is a Bad Idea.

So the only way to add an uncustomized file is with the File element in the feature definition.  And the only way to overwrite an existing file is with code.  How then can we add an uncustomized file and overwrite an existing file at the same time?

Easy: By adding the file with a different name, then use code to move it and replace the original file.

In the feature:

<File Path="Pages\defaultv2.aspx" Url="defaultv2.aspx"/>

And in the FeatureActivated event of the feature receiver:

SPFile sourceFile = site.RootWeb.GetFile("defaultv2.aspx");
sourceFile.MoveTo("default.aspx", true);

Now default.aspx will be read from your location instead of the old one.

The best solution is obviously not to overwrite files that are part of the standard site template at all.  In this example, we could have instead changed the WelcomePage of the site to defaultv2.aspx, like this:

SPFolder rootFolder = site.RootWeb.RootFolder;
rootFolder.WelcomePage = "defaultv2.aspx";
rootFolder.Update();

But there may be circumstances where you want to keep the original URL, for instance if users may have already bookmarked it.  Then you need to do it this way.

Error occurred in deployment step ‘Retract Solution’: The language-neutral solution package was not found.

We don’t know why this happens, possibly some beta problem, but one solution is to call the Delete method on the solution directly, using PowerShell:

(get-spsolution mysolution.wsp).Delete()

You can also run get-spsolution without parameters to see which solutions are currently installed in the farm.

Before you read this you should be familiar with the web config modification framework in SharePoint.  It’s important never to modify SharePoint web.config files directly, especially when you’re deploying your solutions to a farm environment.

Let’s say the standard web.config modifications made by our solution look like this:

<configuration>

<ourproduct>

<standard-element>

<sub-element/>

</standard-element>

</ourproduct>

</configuration>

.. and then somebody adds an attribute and a node to this for a particular customer, like this:

<configuration>

<ourproduct>

<standard-element custom-property=”x”>

<sub-element/>

</standard-element>

<custom-element/>

</ourproduct>

</configuration>

.. and now we want to update the standard section like this:

<configuration>

<ourproduct>

<standard-element custom-property=”x”/>

<custom-element/>

<another-standard-element/>

</ourproduct>

</configuration>

We’ve removed one element, and added another.  And we want to deploy this to all installations where our solution is in use, without knowing which (or if) custom elements may have been added.

Using Sequence and Owner

As long as we only add new nodes, and never remove old ones, we could simply add new web config modifications to SharePoint.  But I’m going to describe a solution that I think is cleaner, and also allows you to delete some of the standard elements.

The key is the Sequence and Owner properties of the SPWebConfigModification class.  Owner is used to keep track of who owns a modification, and should be the same for all modifications added by a particular feature.  That way, when the feature deactivates, it can just loop through all the web config modifications, and delete the ones with that name.

Sequence tells SharePoint in which order to apply modifications.  If you don’t set a Sequence, the order depends on the order you added the modifications in, which becomes fragile if you want to upgrade a feature later.  In our scenario, the standard changes should have a low Sequence, for instance 0, and the custom changes a higher Sequence, such as 10.  That way, when the web.config is updated, the custom changes are always added on top of the standard ones.

(There’s no point in having different Sequence values for each modification in your feature, as they’re always applied in the order you add them.)

Activation and deactivation

So let’s begin with the initial activation.  We have a feature called StandardFeatureX and another called CustomFeatureY.  When each feature activates, they add their modifications:

SPWebConfigModification mod = new SPWebConfigModification(“ourproduct”, “configuration);

mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;

mod.Value = “<ourproduct><standard-element><sub-element/></standard-element></ourproduct>”;

mod.Owner = “StandardFeatureX”;

mod.Sequence = 0; // 10 for the custom feature

webApp.WebConfigModifications.Add(mod);

And when they are deactivated, they delete them, checking the Owner property to make sure they remove everything:

List<SPWebConfigModification> modsToDelete = new List<SPWebConfigModification>();

foreach (SPWebConfigModification existingMod in webApp.WebConfigModifications)

{

if (existingMod.Owner == “StandardFeatureX”)

{

modsToDelete.Add(existingMod);

}

}

foreach (SPWebConfigModification modToDelete in modsToDelete)

{

webApp.WebConfigModifications.Remove(modToDelete);

}

After the modifications have been added or removed, we apply the modifications, like this:

webApp.Update();

webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

So if we first activate StandardFeatureX, and then CustomFeatureY, we get the result in the second example above.  (We can then later deactivate the features in the opposite order to return web.config to its initial state.)

Upgrading the standard modifications

But now we want to change StandardFeatureX so that we get the result in the third example above.  How do we do that?  If you simply deactivate and activate StandardFeatureX, SharePoint won’t know what to do with the modifications from CustomFeatureY in the mean time.  And we can’t deactivate CustomFeatureY, because we don’t know that it exists.

The solution is to use a feature upgrade, as described in an earlier post, and then in the FeatureUpgrading method do the following:

[Remove all our old modifications]

[Add all our modifications back again, the way they're supposed to look now]

webApp.Update();

webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

The trick is to not apply the modifications until the end, when we’re done.  SharePoint does not update web.config files immediately when you add or remove a modification.  It waits until you call ApplyWebConfigModifications.  So it’s okay that the first step leaves the modifications in an invalid state, as long as it’s made valid again immediately afterwards.

And when you do call ApplyWebConfigModifications, the modifications are made in the order of their Sequence values first, and the order they were added second, like this:

Sequence 0, added first

Sequence 0, added second

Sequence 10, added first

Sequence 10, added second

It’s still possible that the standard changes will conflict with the custom changes, of course.  You can only remove elements that are not open for customization.  But this approach allows you make non-conflicting upgrades that might otherwise be difficult, and it allows you to have a few big chunks of XML that you add new elements to, instead of making every change as a separate modification.

Behind the scenes

When you’re working with web.config modifications it’s useful to look at the modifications that are currently in effect on a web application.  Use this PowerShell command:

(get-spwebapplication http://mysite).WebConfigModifications | select Name, Path, Sequence, Owner

Writing the upgrade code

Add an event receiver to your feature, and uncomment the FeatureUpgrading method.  This method will run whenever your feature is being upgraded.

Next, go to the feature properties, and copy the values for Receiver Assembly and Receiver Class to Upgrade Actions Receiver Assembly and Upgrade Actions Receiver Class, and set an initial value for the Version property, for instance 1.0.0.0.

The Version is on the same format as .Net assembly versions, ie. Major.Minor.Build.Revision.

Deploy the solution, then go back and increase the Version, for instance to 1.0.0.1.  Open the feature designer, and click on Manifest.

Click on Edit options.  This allows you to add XML to your feature that will be merged with what you’ve configured in the feature designer and the feature properties.  Enter the following:

<?xml version=”1.0″ encoding=”utf-8″ ?>

<Feature xmlns=”http://schemas.microsoft.com/sharepoint/“>

<UpgradeActions>

<VersionRange>

<CustomUpgradeAction Name=”DoTheUpgrade”/>

</VersionRange>

</UpgradeActions>

</Feature>

You can specify multiple VersionRange elements that apply different upgrade actions to different version ranges, by using the BeginVersion and EndVersion attributes.  If you don’t specify these values, like above, the same upgrade actions are taken no matter which version we’re upgrading from, so then it’s up to your code to determine what it needs to do. You can access the latest and current version numbers from properties.Definition.Version (latest) and properties.Feature.Version (current).

The CustomUpgradeAction element is the node that actually triggers the call to FeatureUpgrading.  The Name property is sent to the method as the parameter upgradeActionName, and you can use that to determine which upgrade action to perform, like this:

<VersionRange BeginVersion=”1.0.0.0″ EndVersion=”2.0.0.0″>

<CustomUpgradeAction Name=”UpgradeToV2″/>

</VersionRange>

<VersionRange BeginVersion=”2.0.0.0″ EndVersion=”3.0.0.0″>

<CustomUpgradeAction Name=”UpgradeToV3″/>

</VersionRange>

And in the feature receiver class:

public override void FeatureUpgrading(SPFeatureReceiverProperties properties, string upgradeActionName, System.Collections.Generic.IDictionary<string, string> parameters)

{

switch (upgradeActionName)

{

case “UpgradeToV2″:

..

case “UpgradeToV3″:

..

}

}

We can now deploy the new version.  Do not use Visual Studio to do this, since the default deployment action in Visual Studio is to retract the solution and then add it back in again.  Instead, just package the solution, then use the update-spsolution command in PowerShell:

update-spsolution -identity SharePointProject3.wsp -literalpath bin\Debug\SharePointProject3.wsp -GACDeployment

(Note: You should probably start a new instance of PowerShell after each time you build, otherwise the actions you perform may be run against an outdated version of your assembly from the GAC.  The same thing sometimes applies to Visual Studio deployment, for instance if one solution refers to an assembly in another solution – hopefully this is a bug in the beta.)

Performing the upgrade

At this point the new version of the feature has been installed, but it has not been upgraded on the sites where it is in use.  You can verify this by running the following script in PowerShell:

get-spfeature | where {$_.DisplayName -eq “FeatureName”} | select DisplayName, Version

This is the latest version.  Here’s the version currently in use on your site:

(get-spsite http://[siteurl]).Features | where {$_.Definition.DisplayName -eq “FeatureName”} | select Version

If you’ve done everything correctly, the versions should differ.  It’s now time to perform the actual upgrade.  Features aren’t upgraded automatically.  There are two ways to trigger an upgrade, one slow and one quick.

The slow way is to run psconfig:

psconfig -cmd upgrade -inplace b2b

This will take several minutes, but is probably the correct way to perform an upgrade in a test or production environment.  “-inplace b2b” means that features will be upgraded if any part of the version has been increased, even the build or revision number.  If you specify “-inplace v2v”, features will only be upgraded if the major or minor version number has increased, ie. 1.1.0.0 => 1.2.0.0.

A quicker way to perform an upgrade is to call the Upgrade method on the SPFeature object directly on the site where it is activated.

$site = get-spsite http://siteurl

$enabledfeature = $site.Features | where {$_.Definition.DisplayName -eq “FeatureName” }

if($enabledfeature)

{

$enabledfeature.Upgrade($false)

}

This may be a useful script to run on your development server when you want to test that your upgrade code is running correctly.

Now if you check the current version again, it should be the latest version.  Note that you’re upgrading the feature only on one particular site.  Also note that the feature in this example is Site-scoped.  For other scopes, run the upgrade at the appropriate level.

In addition to executing upgrade code, you can also specify other actions in the VersionRange element, such as adding a field to a content type, or renaming a module file.

Sources and more information

Corey Roth: Feature Versioning and Upgrades in SharePoint 2010

Dave Graham: In-place Upgrade of Solutions in SharePoint 2010

MSDN: How to: Use Upgrade Code to Activate a Feature with Dependencies

But when PowerShell finally did arrive, in 2006, it was as good as the Unix alternatives, and in one important way superior: Object piping.  PowerShell allows you to string commands together and pipe the results of one as input to the next, as .Net objects.  In a SharePoint 2010 context, that allows you to do this:

get-spsite | get-spweb -filter {$_.Template -eq “STS#0″ } | foreach-object { enable-spfeature -identity LinksList -force -url $_.Url }

get-spsite without parameters returns all site collections in the farm, get-spweb looks for every site in those site collections that use the site template STS#0 (Team Site), and then the foreach command loops through each of these sites and enables the LinksList feature on them.  ($_ refers to the current object in the foreach loop.  The same syntax is used in related commands such as where-object, which filters results based on a condition.)

In short, this command finds all sites based on a given template, and activates a feature on them.

Is this useful?  Yes – for SharePoint 2007 I made my own deployment tool just to do things like that.  Now it’s just a line of commands.

PowerShell syntax is a bit daunting.  Even if you know the basic concepts from a Unix shell, there are a lot of commands to get familiar with.  So probably the most important thing to learn in PowerShell as a beginner is how to get help about the available commands.  Which, in the literal-minded world of PowerShell you do by typing, well, get-help:

get-help

To get help about a particular command, write get-help commandname, for instance:

get-help get-command

get-help get-command -examples

The first will tell you how to use get-command, which allows you to find all the available commands, and the -examples parameter will show you examples of how to use it.  -examples can be used with all PowerShell commands.

To get all SharePoint commands in PowerShell, write:

get-command -module Microsoft.SharePoint.PowerShell

To get all commands for the SPWeb (site) object, write:

get-command -noun SPWeb

All PowerShell are built up on the format verb-noun, for instance get-spweb, so when we ask for all commands where the noun is SPWeb, we get get-spweb, export-spweb, new-spweb, remove-spweb, etc.

You can also dig into the properties and methods of the objects you retrieve:

get-spweb http://servername | get-member

get-spweb http://servername | select *

The first gives you a list of all the properties and methods that exist on an SPWeb object.  The second retrieves all the property values on that object.

One aspect of working with SharePoint in PowerShell that probably will trip people up, because it’s unintuitive, is that you must use start-spassignment and stop-spassignment to prevent SPWeb and SPSite objects you’re working with from being automatically disposed.  For instance:

start-spassignment -global

$web = get-spweb http://servername

[operate on the $web object here]

stop-spassignment -global

The -global parameter means that no objects will be disposed at all until stop-spassignment is called.  So you can safely work with anything you instantiate.  It’s also possible to do this with individual objects, which is useful to prevent memory bloat in complex scripts.  See the documentation on start-spassignment for more on this.

There are four approaches to BCS, two of them are comparatively easy and can be used with SharePoint Designer, and the other two are more difficult and are used with Visual Studio.

The easy approaches: Database and WCF connections with SharePoint Designer

If you’re doing a fairly simple integration, and if your data are available from a database or a WCF service, you can accomplish a lot with SharePoint Designer, which has really become a must-have tool for working with SharePoint 2010.

That’s not to say that everything about this is easy.  Setting up relations between different external content types is unintuitive, nor could I get navigation across these relations to work, (this is either a bug with me or the beta).  But you can achieve a lot by clicking around a bit.

More information:

• How to: Create External Lists in SharePoint
• How to: Add an Association between Two External Content Types
• ..more BCS howto’s

The hard approaches: .Net assemblies and custom connectors with Visual Studio

It’s a bit unfair to group these two together: Defining external content types in .Net assemblies has very good tool support within Visual Studio 2010.  Custom connectors, by contrast, appear not to be documented at all, at the moment.

The .Net assembly approach involves using Visual Studio to edit the BDC model that defines your external content types, and write classes that contain logic for retrieving and updating data.  Visual Studio contains a BDC Explorer which you can use to work with the underlying XML file that defines the model.  The tools are very good, compared to editing the XML by hand, but it doesn’t actually make the task any less complex, it just provides a visual interface for it.

One immediate stumbling block for developers will probably be that you have to define every property of your data types every time you refer to them.  For instance, you can’t just say “this is what a Product looks like, and I want to return it from these five methods”.  You say “I want this method to return something called Product, which looks like this, and I want this other method to return something called Product, which looks like this, and .. etc.”

The error messages aren’t helpful.  For instance, I got this error when trying to create a list for an external content type I had defined in .Net: “Could not save changes.  No Finders available in the View Group associated with the SpecificFinder (Read Item) operation ‘ReadItem’ on Entity (External Content Type) with Namespace = ‘..’, Name = ‘..’.  The list cannot be created.”

Huh?  It turned out that I had misspelled a property name, so that the BDC model referred to a property that didn’t exist, but there were no error messages anywhere that said so, or even said which property or type descriptor that caused the problem.

When you use the .Net assembly approach, you need to define classes for everything you want to return.  This becomes a limitation if you want to expose a large data model, or if the model is dynamic.  In those cases you should consider making a custom connector, which allow you to decide everything about how you read and update data for yourself.

Custom connectors are also written in .Net, but you get no tool support from Visual Studio.  Nor is there much documentation about how to make one.  Hopefully there will be more later, because this will probably be the right approach for many advanced scenarios.

More information:

• Using Business Connectivity Services in SharePoint 2010
• HOW TO: Programmatically create a SharePoint 2010 External Content Type
• Differences Between Using the .NET Assembly Connector and Writing a Custom Connector

Conclusion

This is going to be big.  BCS has its oddities, and will not be easy to master, but the payoff from doing so is potentially huge, so anyone who works with SharePoint development should get familiar with it.

There are several SharePoint objects one can consider to look in, for example SPWeb or SPUser to get the users selected language. In the picture below I have added a screenshot of a debugging session with the various relevant values I found.

In order to get the language selected by the user, you will have to access the property System.Globalization.CultureInfo.CurrentUICulture. Properties like SPContect.Current.Web.UICulture is not affected by the user selected language.