In this article we explore how to update multiple web configuration files in a Farm environment. The configuration file is the Internet Information Services (IIS) web application configuration file. It is residing in the IIS folder.
For example: C:\inetpub\wwwroot\wss\VirtualDirectories\80\web.config
Abstract
SharePoint 2010 Farm Deployment may involve multiple Web Front End servers. For example a typical farm environment is as follows:
- 2 Web Front End Servers
- 1 Database Server
- 1 Search Index Server
In this case any update to the web.config file should be done in the 2 servers. Manually updating both the servers is tedious and not recommended once we are deploying a feature to a user.
Solution
We can use the SPWebConfigModification server object model for this purpose.
The following are some of the entry types possible with this:
- Safe Control
- Connection String
- Application Setting
SPWebConfigModification is in the namespace Microsfot.SharePoint.Administration.
Note: The configuration modification through SPWebConfigModification server object model is the recommended one since it does a safe update.
Important Properties
The following are the important properties of the SPWebConfigModification class:
- Name to hold name of attribute / section
- Value to hold value of the item
- Path to hold the X Path to the node
Adding a Safe Control
The following is the code for adding a Safe Control entry into the web.config. Create a new SharePoint 2010 Console Application and execute the following code which creates an entry for "TestAssembly".
SPWebService service = SPWebService.ContentService;
SPWebConfigModification modification = new SPWebConfigModification();
modification.Owner = "OwnerNameHere";
modification.Path = "configuration/SharePoint/SafeControls";
modification.Name = "SafeControl[@Assembly='TestAssembly'][@Namespace='TestNameSpace'][@TypeName='*'][@Safe='True']";
modification.Sequence = 0;
modification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
modification.Value = "<SafeControl Assembly='TestAssembly' Namespace='TestNameSpace' TypeName='*' Safe='True' />";
service.WebConfigModifications.Add(modification);
service.ApplyWebConfigModifications();
service.Update();
Later you can open the web.config file and see the new entry there.
Code Explained
The SPWebConfigModification class instance holds the modification information like:
- Name
- Value
- Path
- Owner
- Sequence
The WebConfigModifications property contains all the modification entries. (Modifications stored in the Database.) We are adding our modification entry into this collection.
The ApplyWebConfigModifications () applies all the Modifications to the servers in a farm.
The Update() method saves the WebConfigModifications into the Content database. This will help to re-deploy all the modifications in the future.
Note: Please make sure you have set the Platform Target of the project as .Net 3.5 Framework.
Adding a Connection String
Now let us try adding a connection string into the web.config files of multiple servers in the farm. Create a new method in our Console Application and add the following code to it.
private static void CreateConnectionString()
{
SPWebService service = SPWebService.ContentService;
SPWebConfigModification modification = new SPWebConfigModification("CS1", "configuration/connectionStrings");
modification.Owner = "OwnerZ";
modification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
modification.Value = "<add name=\"CS1\" connectionString=\"Data Source=SERVER;User ID=USER;Password=PASSWORD;Initial Catalog=DBNAME;\" providerName=\"System.Data.SqlClient\"/>";
service.WebConfigModifications.Add(modification);
service.ApplyWebConfigModifications();
service.Update();
}
Later you can open the web.config file and see the new entry there.
Please note that the preceding code is performing the following:
-
Specify the Web Service
-
Specify the Modification Name and X Path
-
Specify the add tag with Connection String
-
Add to Modifications list
-
Apply Modification
-
Save Modifications list to content database
Note: If you encounter any error saying the section does not exist then you can manually create an empty connection string section in the configuration file.
Adding an Application Setting
We can also add an Application Setting to the configuration file. Create a new method named CreateAppSetting() inside the console application we have and use the following code for adding an application setting to the web application configuration file.
private static void CreateAppSetting()
{
SPWebService service = SPWebService.ContentService;
SPWebConfigModification modification = new SPWebConfigModification("AppSetting", "configuration/appSettings");
modification.Owner = "OwnerZ";
modification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
modification.Value = "<add key=\"MYKEY\" value=\"MYVALUE\" />";
service.WebConfigModifications.Add(modification);
service.ApplyWebConfigModifications();
service.Update();
}
Later you can open the web.config file and see the new entry there.
Please note that the preceding code is performing the following:
-
Specify the Web Service
-
Specify the Modification Name and X Path
-
Specify the add tag with KEY & VALUE
-
Add to Modifications list
-
Apply Modification
-
Save Modifications list to content database
Importance of Owner Property
We are using the Owner property (which is a string) to specify the owner name of the modification. In the future the specified property can be used to filter modifications based on the Owner.
So setting the Owner property gives the following advantages:
-
Finding Modification entries by Owner
-
Updating Modification entries by Owner
-
Removing Modification entries by Owner
The following is the example code that will remove modification entries by owner.
private static void RemoveByOwner(string owner)
{
SPWebService service = SPWebService.AdministrationService;
service.WebConfigModifications.Where(m => m.Owner == owner).ToList().
ForEach(m => service.WebConfigModifications.Remove(m));
service.Update();
}
Under the Hood
Each of the Configuration Modification entries are stored in the SharePoint Content database. This is to track all the changes made using the SPWebConfigurationModification class.
Please note that there could be various SharePoint solutions creating configuration modification entries.
Why is a History of Modifications maintained?
You might be wondering why the history of modifications is maintained. This is to apply all the changes to multiple front-end servers.
Each of the Configuration Modification entries are stored in the Content database. At a later point of time when a new server is added to the farm, a quick update is possible.
Without storing the entries in the database it is difficult to parse a valid server configuration file and replicate the changes to another.
Various Locations of web.config
Please note that there are various locations for the web.config files depending on the context and element.
The SharePoint Port 80 Application web.config resides in:
C:\inetpub\wwwroot\wss\VirtualDirectories\80
SharePoint Central Administration Application web.config resides in:
C:\inetpub\wwwroot\wss\VirtualDirectories\[Port of Central Administration]
SharePoint Port 80 Application Web Part web.config resides in:
C:\inetpub\wwwroot\wss\VirtualDirectories\80\wpresources
Additionally there is a CONFIG folder inside the 14 Hive:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG
This folder contains the following types of files:
-
web.config
-
*.config
-
webconfig.*.xml
More information on these can be found through the References section.
Note: The Safe Control entries can also be deployed to the CONFIG folder as a webconfig.*.xml file. The entries will be merged with the web.config file.
References
http://tinyurl.com/sp2010-spwbcfg
Summary
In this article we have explored the problems with updating multiple web configuration files and the usage of the SPWebConfigModification model to resolve it.
The following are the points worth noting:
-
SPWeConfigModification can be used to create modification entries
-
The Update() method will save the entry to a database
-
Multiple Modification entries are tracked in the database
-
The ApplyWebConfigModifications() method applies the modification entries in the database to servers in a farm
-
Adding / Updating / Deleting of configuration entries is a little tricky
In real-world scenarios this model should give an advantageous edge for the developer and it is the recommended way for doing configuration modifications.
The source code contains the example we have discussed.