Requirements
|
RadControls version
|
2008 Q2 (2008.2.826.20)
|
.NET version
|
v2.0.50727
|
Visual Studio version
|
2008
|
programming language
|
VB.NET
|
browser support
|
N/A
|
PROJECT DESCRIPTION
Deploying custom features and solutions for SharePoint is something of pain... start to add 3rd party components into the mix and you have a debugging and deployment soup, come nightmare. Using only the power of a bit of code and the extensibility of the SharePoint STSADM command framework, we can make the task of deploying 3rd party components, along with features and solutions, a breeze.
If you are implementing (and customising) the odd SharePoint server, this article is overkill. However, if you are implementing many SharePoint environments or even multi-server farm environments this article should help you to reduce your development and deployment time.
Integrating 3rd party components presents two challenges. The first relates to how you deploy the component file(s) within your feature/solution package and is beyond the scope of this article. The second problem is how to ensure that the web.config file is suitably updated for all servers within a farm – the primary focus of this article.
Manually resolving this issue is something of a dark-art... locating the right web.config file, backing up the file, and making delicate amendments are all fraught with danger. One wrong move and your farm could be in trouble! We need to automate this.
One approach is to use the SharePoint object model to amend the web.config; the code can be easily placed within the activation/installation code of any feature/solution. Whilst this is helpful for the one-off projects, it is not suitable for reuse when you start to address a few more projects.
A more subtle approach is to extend the functionality provided by SharePoint’s STSADM utility, in essence, a custom STSADM command that can be executed to perform web.config amendment, assembly registration and much more.
To create a custom STSADM command, the first point of reference is an article on MSDN on the ISPStsadmCommand interface, which is located in Microsoft.SharePoint.dll. As with almost all SharePoint document, explanations and examples are a bit thin – given the scale of the product, I’m not surprised.
The interface points to two specific methods that must be implemented, GetHelpMessage and Run. GetHelpMessage is a simple string function that when invoked displays the string returned to the users console window. The Run method is where the real magic is contained and it is your job to put the magic in:
1 |
Public Function Run(ByVal command As String, ByVal keyValues As System.Collections.Specialized.StringDictionary, ByRef output As String) As Integer Implements Microsoft.SharePoint.StsAdmin.ISPStsadmCommand.Run |
2 |
Try |
3 |
Me._command = command.ToLowerInvariant |
4 |
Me._WebAppUrl = keyValues("url") |
5 |
If String.IsNullOrEmpty(Me._WebAppUrl) Then |
6 |
Throw New TelerikWssException("You must specific the -url parameter for this command.") |
7 |
End If |
8 |
Try |
9 |
Me._SpSite = New SPSite(Me._WebAppUrl) |
10 |
Me._SpWebApp = Me._SpSite.WebApplication |
11 |
Catch ex As Exception |
12 |
Throw New TelerikWssException(String.Format("Could not obtain a reference to the web application at the following URL '{0}', because {1}. See inner exception for further information.", Me._WebAppUrl, ex.Message), ex) |
13 |
End Try |
14 |
Select Case _command |
15 |
Case "installtelerik" |
16 |
Me.InstallTelerik(output) |
17 |
Case "uninstalltelerik" |
18 |
Me.UninstallTelerik(output) |
19 |
Case Else |
20 |
Throw New TelerikWssException(String.Format("The command '{0}' was not recognised.", _command)) |
21 |
End Select |
22 |
Return 0 |
23 |
Catch ex As Exception |
24 |
Try |
25 |
output = "An exception was thrown during the execution of this STSADM command: " & ex.Message |
26 |
Diagnostics.EventLog.WriteEntry("Telerik.WSS STSADM Command", ex.Message, Diagnostics.EventLogEntryType.Error) |
27 |
Catch |
28 |
End Try |
29 |
Finally |
30 |
End Try |
31 |
End Function |
In the case of creating a custom STSADM command for configuring Telerik, we can use this routine (along the SharePoint object model) to locate a specific web application and amend its web.config:
1 |
cfg = New ConfigEntry |
2 |
With cfg |
3 |
.Name = "SafeControl[@Assembly='Telerik.Web.UI, Version=2008.2.826.20, Culture=neutral, PublicKeyToken=121fae78165ba3d4']" |
4 |
.Path = "configuration/SharePoint/SafeControls" |
5 |
.Value = "<SafeControl Assembly=""Telerik.Web.UI, Version=2008.2.826.20, Culture=neutral, PublicKeyToken=121fae78165ba3d4"" Namespace=""Telerik.Web.UI"" TypeName=""*"" Safe=""True"" />" |
6 |
.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode |
7 |
End With |
8 |
entries.Add(cfg) |
Furthermore, we can use object model to push the updates throughout the farm... in fact, you could even leave the task in the hands of your SharePoint or server administrator.
1 |
Me._SpWebApp.Farm.Services.GetValue(Of SPWebService).ApplyWebConfigModifications() |
2 |
Me._SpWebApp.Update() |
Contained within the code files attached with this article is a complete VB.NET solution. The STSADM command will only ensure that a specific version of Telerik RadControls DLL is registered within the SafeControls, Assemblies and Namespaces sections of a given web application
STSADM Command Installation
1. Ensure that the target machine has SharePoint Services 3.0 or Office SharePoint Server 2007 installed
2. Log in under then local/domain administrator account on the target machine.
3. Unpack the zip file content to a folder on C:\
4. Locate the WSP folder within the solution
5. Open a command console and execute the install.bat
STSADM Command Operation
1. Ensure that the target machine has SharePoint Services 3.0 or Office SharePoint Server 2007 installed
2. Log in under then local/domain administrator account on the target machine.
3. Open a command console and execute the following STSADM command, replacing http://myserver:80 with the full URL of your SharePoint web application:
1 |
STSADM –o InstallTelerik –url http://myserver:80 |
4. If you need to reverse the operation, execute the following STSADM command, replacing http://myserver:80 with the full URL of your SharePoint web application:
1 |
STSADM –o UninstallTelerik –url http://myserver:80 |
Note: If you are modifying the solution files, ensure that you run the BuildWSP.bat file using a command console. This will update the solution package that is installed when you execute install.bat.
Summary
This article has outlined the basis for a simple, yet powerful approach to set-up of Telerik components within a web.config file. The custom command framework outlined can be easily extended further to include more time-saving features. For example, the solution can be easily modified to include automated support for AJAX, Component-specific elements (such as RadSpell/RadUpload), HttpModules, HttpHandlers and custom web.config entries that are more specific to your needs.