If you’ve done any development on SharePoint 2010 using Visual Studio, you’ve probably noticed some files in your project that include strings like $SharePoint.Project.AssemblyFullName$ or $SharePoint.Package.Name$. These token strings are called Replaceable Parameters. When your SharePoint Solution (.wsp) is being packaged by Visual Studio, the packaging tool will search for and replace these tokens with values that are not known at design time.

Some of you probably remember doing this process manually with SharePoint 2007 projects. Build the solution; copy the DLL to the GAC; view properties of assembly in the GAC and copy PublicKeyToken; finally, create the assembly full-name string by hand and paste it back into a manifest file, etc. It was time-consuming and error-prone, though some third-party tools did help with this process.

Now, we can leverage Replaceable Parameters to avoid this process and do lots more. These parameters can be useful for single developer projects all the way to large projects using TFS with automated builds.

Let’s use an example to illustrate injecting a class name for an event receiver into a feature.

First, we need to create a new project in Visual Studio. Choose the “Empty SharePoint Project” template from the list.


Figure 1

Next, add an Event Receiver to the item to the project. I called mine EventReceiver1. For the event receiver settings, I chose list events and Document Library as my event source. To complete the wizard, choose the specific events that you’d like to implement handlers for and click Finish.


Figure 2


Figure 3

Visual Studio will now build a class to contain our handlers and a feature to provision the handler to a site. These items should now appear in Solution Explorer, and the class for our handlers will be open.


Figure 4


Figure 5

Expand the EventReceiver1 element and open the Elements.xml file. This is where our feature is going to wire up the event handlers to our SharePoint environment.

<?xml version=”1.0″ encoding=”utf-8″?>
<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>
  <Receivers ListTemplateId=”101″>
      <Receiver>
        <Name>EventReceiver1ItemDeleting</Name>
        <Type>ItemDeleting</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>SharePointProject2.EventReceiver1.EventReceiver1</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
 
  </Receivers>
</Elements>

As you can see, Visual Studio has already inserted a Replaceable Parameter to inject the fully qualified name of our assembly. It has also already inserted the class name for our handler code.

But what if we decide to change the name of our class, or we refactor the solution and the namespace changes? We could solve the problem by using a global find and replace. This is only one scenario, and already we have a couple pitfalls to watch out for. We have to 1) remember to perform the find-replace, and 2) manually check to make sure all instances are accounted for. It doesn’t seem like much work for our simple exercise. But, you can see how this could become a fair amount of manual and error-prone work if we had a larger solution with many more event receivers.

Instead of relying on someone to do all that work, let’s use a Replaceable Parameter to inject the class name into the elements.xml file for us. The Replaceable Parameter we’ll use is $SharePoint.Type.<GUID>.FullName$. Here are the steps to follow:

1. Open the EventReceiver1.cs file and insert a Guid attribute tag just before our class declaration:

[System.Runtime.InteropServices.Guid(“45003CBB-793C-40DE-828C-3951FFE4752F”)]
publicclassEventReceiver1:SPItemEventReceiver

You can easily do this using the Tools > Create GUID menu option. Then, choose Format 5 (C#) or 6 (VB) to generate the attribute tag.

Important Note: Make sure you use the System.Runtime.InteropServices namespace when resolving namespaces. You don’t want to decorate your class with a System.Guid.

2. Now, we can add our Replaceable Parameter to our elements.xml file. Replace the following xml:

<Class>SharePointProject2.EventReceiver1.EventReceiver1</Class>

With this:

<Class>$SharePoint.Type.45003cbb-793c-40de-828c-3951ffe4752f.FullName$</Class>

Important Note: When replacing the <GUID> token with the Guid you generated for your class, you MUST make it all lowercase.

That’s all there is to it. Now, we won’t ever have to worry about our class name or namespace changing. Visual Studio will automatically inject our class name when it packages our SharePoint Solution.

For a complete list of Replaceable Parameters and more information, visit http://tinyurl.com/replaceableparameters.

SharePoint911 consultant Phil Jirsa has been developing business applications for the Web since 1999. He began developing with .NET in 2001 and SharePoint technologies in 2004. Phil has been a speaker at numerous community training events and user groups.