SharePoint 2010 Replaceable Parameter, some observations…

SharePoint Tools for Visual Studio 2010 provides a rudimentary mechanism for replaceable parameters that you can use in files that are not compiled, like ascx files and your project property settings. The basics on this can be found in the documentation at http://msdn.microsoft.com/en-us/library/ee231545.aspx.

There are some quirks however. For example:

My Package name is MacawMastSP2010Templates, as defined in my Package properties:

image

I want to use the $SharePoint.Package.Name$ replaceable parameter in my feature properties. But this parameter does not work in the “Deployment Path” property, while other parameters work there, while it works in the “Image Url” property. It just does not get expanded. So I had to resort to explicitly naming the first path of the deployment path:

image :

You also see a special property for the “Receiver Class” in the format $SharePoint.Type.<GUID>.FullName$. The documentation gives the following description:The full name of the type matching the GUID in the token. The format of the GUID is lowercase and corresponds to the Guid.ToString(“D”) format (that is, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Not very clear. After some searching it happened to be the guid as declared in my feature receiver code:

image

In other properties you see a different set of replaceable parameters:

image

We use a similar mechanism for replaceable parameter for years in our Macaw Solutions Factory for SharePoint 2007 development, where each replaceable parameter is a PowerShell function. This provides so much more power.

For example in a feature declaration we can say:

Code Snippet
  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <!-- Template expansion
  3.      [[ProductDependency]] -> Wss3 or Moss2007
  4.      [[FeatureReceiverAssemblySignature]] -> for example: Macaw.Mast.Wss3.Templates.SharePoint.Features, Version=1.0.0.0, Culture=neutral, PublicKeyToken=6e9d15db2e2a0be5
  5.      [[FeatureReceiverClass]] -> for example: Macaw.Mast.Wss3.Templates.SharePoint.Features.SampleFeature.FeatureReceiver.SampleFeatureFeatureReceiver
  6. -->
  7. <Feature Id="[[$Feature.SampleFeature.ID]]"
  8.   Title="MAST [[$MastSolutionName]] Sample Feature"
  9.   Description="The MAST [[$MastSolutionName]] Sample Feature, where all possible elements in a feature are showcased"
  10.   Version="1.0.0.0"
  11.   Scope="Site"
  12.   Hidden="FALSE"
  13.   ImageUrl="[[FeatureImage]]"
  14.   ReceiverAssembly="[[FeatureReceiverAssemblySignature]]"
  15.   ReceiverClass="[[FeatureReceiverClass]]"
  16.   xmlns="http://schemas.microsoft.com/sharepoint/">
  17.     <ElementManifests>
  18.         <ElementManifest Location="ExampleCustomActions.xml" />
  19.         <ElementManifest Location="ExampleSiteColumns.xml" />
  20.         <ElementManifest Location="ExampleContentTypes.xml" />
  21.         <ElementManifest Location="ExampleDocLib.xml" />
  22.         <ElementManifest Location="ExampleMasterPages.xml" />
  23.  
  24.         <!-- Element files -->
  25.         [[GenerateXmlNodesForFiles -path 'ExampleDocLib\*.*' -node 'ElementFile' -attributes @{Location = { RelativePathToExpansionSourceFile -path $_ }}]]
  26.         [[GenerateXmlNodesForFiles -path 'ExampleMasterPages\*.*' -node 'ElementFile' -attributes @{Location = { RelativePathToExpansionSourceFile -path $_ }}]]
  27.         [[GenerateXmlNodesForFiles -path 'Resources\*.resx' -node 'ElementFile' -attributes @{Location = { RelativePathToExpansionSourceFile -path $_ }}]]
  28.     </ElementManifests>
  29. </Feature>

We have a solution level PowerShell script file named TemplateExpansionConfiguration.ps1 where we declare our variables (starting with a $) and include helper functions:

Code Snippet
  1. # ==============================================================================================
  2. # NAME: product:\src\Wss3\Templates\TemplateExpansionConfiguration.ps1
  3. #
  4. # AUTHOR: Serge van den Oever, Macaw
  5. # DATE  : May 24, 2007
  6. #
  7. # COMMENT:
  8. # Nota bene: define variable and function definitions global to be visible during template expansion.
  9. #
  10. # ==============================================================================================
  11. Set-PSDebug -strict -trace 0 #variables must have value before usage
  12. $global:ErrorActionPreference = 'Stop' # Stop on errors
  13. $global:VerbosePreference = 'Continue' # set to SilentlyContinue to get no verbose output
  14.  
  15. # Load template expansion utility functions
  16. . product:\tools\Wss3\MastDeploy\TemplateExpansionUtil.ps1
  17.  
  18. # If exists add solution expansion utility functions
  19. $solutionTemplateExpansionUtilFile = $MastSolutionDir + "\TemplateExpansionUtil.ps1"
  20. if ((Test-Path -Path $solutionTemplateExpansionUtilFile))
  21. {
  22.     . $solutionTemplateExpansionUtilFile
  23. }
  24. # ==============================================================================================
  25.  
  26. # Expected: $Solution.ID; Unique GUID value identifying the solution (DON'T INCLUDE BRACKETS).
  27. # function: guid:UpperCaseWithoutCurlies -guid '{...}' ensures correct syntax
  28. $global:Solution = @{
  29.     ID = GuidUpperCaseWithoutCurlies -guid '{d366ced4-0b98-4fa8-b256-c5a35bcbc98b}';
  30. }
  31.  
  32. #  DON'T INCLUDE BRACKETS for feature id's!!!
  33. # function: GuidUpperCaseWithoutCurlies -guid '{...}' ensures correct syntax
  34. $global:Feature = @{
  35.     SampleFeature = @{
  36.         ID = GuidUpperCaseWithoutCurlies -guid '{35de59f4-0c8e-405e-b760-15234fe6885c}';
  37.     }
  38. }
  39.  
  40. $global:SiteDefinition = @{
  41.     TemplateBlankSite = @{
  42.         ID = '12346';
  43.     }
  44. }
  45.  
  46. # To inherit from this content type add the delimiter (00) and then your own guid
  47. # ID: <base>00<newguid>
  48. $global:ContentType = @{
  49.     ExampleContentType = @{
  50.         ID = '0x01008e5e167ba2db4bfeb3810c4a7ff72913';
  51.     }
  52. }
  53.  
  54. #  INCLUDE BRACKETS for column id's and make them LOWER CASE!!!
  55. # function: GuidLowerCaseWithCurlies -guid '{...}' ensures correct syntax
  56. $global:SiteColumn = @{
  57.     ExampleChoiceField = @{
  58.         ID = GuidLowerCaseWithCurlies -guid '{69d38ce4-2771-43b4-a861-f14247885fe9}';
  59.     };
  60.     ExampleBooleanField = @{
  61.         ID = GuidLowerCaseWithCurlies -guid '{76f794e6-f7bd-490e-a53e-07efdf967169}';
  62.     };
  63.     ExampleDateTimeField = @{
  64.         ID = GuidLowerCaseWithCurlies -guid '{6f176e6e-22d2-453a-8dad-8ab17ac12387}';
  65.     };
  66.     ExampleNumberField = @{
  67.         ID = GuidLowerCaseWithCurlies -guid '{6026947f-f102-436b-abfd-fece49495788}';
  68.     };
  69.     ExampleTextField = @{
  70.         ID = GuidLowerCaseWithCurlies -guid '{23ca1c29-5ef0-4b3d-93cd-0d1d2b6ddbde}';
  71.     };
  72.     ExampleUserField = @{
  73.         ID = GuidLowerCaseWithCurlies -guid '{ee55b9f1-7b7c-4a7e-9892-3e35729bb1a5}';
  74.     };
  75.     ExampleNoteField = @{
  76.         ID = GuidLowerCaseWithCurlies -guid '{f9aa8da3-1f30-48a6-a0af-aa0a643d9ed4}';
  77.     };
  78. }

This gives so much more possibilities, like for example the elements file expansion where a PowerShell function iterates through a folder and generates the required XML nodes.

I think I will bring back this mechanism, so it can work together with the built-in replaceable parameters, there are hooks to define you custom replacements as described by Waldek in this blog post.

No Comments