SPWebConfigModification’s Top 6 Issues
Configuration API introduced in .NET 2.0 gave us whole bunch of options to read and update configuration files such web.config and machine.config files. A very useful framework if you want to dynamically interact with configuration files as they apply to your web applications. WebConfigurationManager possesses all the knowledge of the web.config object model and provides full access to it. The Question is : Can I use this API to access and change web.config files associated with my SharePoint apps? Yes , you certainly can, but you have to keep track of the changes , support the ability to roll them back and more importantly in a farm installation where your app is scaled across multiple web front end servers , your code should be able to reach out to those servers and apply changes (Add/Delete/Update). Although it is not impossible to do it this way, it’s simply more convenient if WSS Object Model could take care of this for us.
Conveniently, WSS object model offers a new class this time around which allows your code (that is within your Feature event receivers , console apps or custom installation applications) to dynamically make and propagate changes to web.config files across your farm using SPWebConfigModification class (Microsoft.SharePoint.Administration namespace). You have the option to add/modify/delete sections, child elements and attributes with some limitations and through many workarounds! We will take a look at some of the issues and workarounds (if there is any:)) in this post.
1) SPWebConfigModification is poorly documented. For example, SPWebConfigModification.Name property or name parameter used in SPWebConfigModification constructor are *NOT* really the names. As Daniel Larson mentions in the community content of this page, SPWebConfigModification.Name property or name parameter in SPWebConfigModification constructor are relative xpaths to the modification. It is very important that you properly set them while adding your modification otherwise when deleting , they won’t be located and removed. WSS engine uses Path property (xpath to the root node for modification) along with Name Property (xpath to the child node from the root node) to delete a modification.
|
|
The following code snippets will add the connection string , but there is NO way that you can delete it.
[CSharp]
SPWebApplication webApp = SPWebApplication.Lookup(new Uri(“http://litware”));
SPWebConfigModification mod = new SPWebConfigModification(“JustaName”, “configuration/connectionStrings”);
mod.Owner = “AnOwner”;
mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
mod.Value = String.Format(“
webApp.WebConfigModifications.Add(mod);
webApp.Update();
webApp.Farm.Services.GetValue
[/CSharp]
OR
[CSharp]
SPWebApplication webApp = SPWebApplication.Lookup(new Uri(“http://litware”));
SPWebConfigModification mod = new SPWebConfigModification();
mod.Name=”JustaName”;
mod.Path=”configuration/connectionStrings”;
mod.Owner = “AnOwner”;
mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
mod.Value = String.Format(“
webApp.WebConfigModifications.Add(mod);
webApp.Update();
webApp.Farm.Services.GetValue
[/CSharp]
The following code snippets will add the connection string and will remove it later on.
Add:
[CSharp]
SPWebApplication webApp = SPWebApplication.Lookup(new Uri(“http://litware”));
SPWebConfigModification mod = new SPWebConfigModification(“add[@name=\”MyConnectionString\”]”, “configuration/connectionStrings”);
mod.Owner = “AnOwner”;
mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
mod.Value = String.Format(“
webApp.WebConfigModifications.Add(mod);
webApp.Update();
webApp.Farm.Services.GetValue
[/CSharp]
Delete:
[CSharp]
SPWebConfigModification configModFound = null;
SPWebApplication webApp = SPWebApplication.Lookup(new Uri(“http://litware”));
Collection
for (int i = 0; i < modsCollection.Count; i++)
{
if (modsCollection[i].Owner == “AnOwner” && modsCollection[i].Name == “add[@name=\”MyConnectionString\”]”)
configModFound = modsCollection[i];
}
if (configModFound != null)
{
modsCollection.Remove(configModFound);
webApp.Update();
webApp.Farm.Services.GetValue
}
[/CSharp]
Note: <connectionStrings></connectionStrings> must be already in your web.config before you try to add a child node (see the related link below) otherwise you get “Failed to apply a web.config modification to file ‘configuration/connectionStrings’. The specified node ‘C:\Inetpub\wwwroot\wss\VirtualDirectories\80\web.config’ was not found in the web.config file. ” . There is even a bug in the exception message thrown by the configuration API (Read the message carefully!). it should say … specified node “configuration/connectionStrings” and file “web.config”… not the other way around ….Anyhow!!:)
2) One thing I noticed that is very annoying is when a web application has been extended to other zones such as Internet, Extranet and etc. In this case modifications propagate across the farm and to all zones as expected. However when you delete the modifications , changes are ONLY applied to the default zone. You have to manually roll back the changes for other zones which really sucks! , but wait !! there is one more thing that sucks more than anything else. No matter what web application you specifiy to be the target of update operation by ApplyWebConfigModifications , it somehow overwrites all the web.config files of other web applications. No , don’t panic!! it doesn’t apply the changes to other web applications , it just somehow opens them up and save them without changeing anything, but this makes the ASP.NET watcher component to force the application pool of those sites to be restarted.
3)Back to issue #2. What if I want to apply my modification only to the Default and Internet zones and not to the other zones? No damn way! SPWebConfigModification doesn’t expose a property that would allow you to specify on which zone(s) you want the WebConfigModification to be applied.
4) If you use EnsureSection, your modifications won’t be deleted (Workaround : use EnsureChildNode instead). I have observed some issues with using EnsureChildNode for adding parent nodes such as appsettings and connectionStrings in MOSS (not WSS). If your code is meant to be executed in both platforms, make sure you completely test your modifications so your code doesn’t mess up with the Web.config files .
[CSharp]
SPWebConfigModification mod = new SPWebConfigModification(“cSection”, “configuration”);
mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureSection;
[/CSharp]
5) SPWebConfigModification CANNOT be used to add some modification types such as assembly(configuration/system.web/compilation/assemblies), assemblyBinding (configuration/runtime/assemblyBinding -SPWebConfigModification doesn’t have a property that would allow you to specify namespace) and etc.
Note: SPWebConfigModification SHOULD NOT be used to add SafeControl or CAS policies to web.config files. Solution package manifests can perfectly handle these type of modifications in SafeControls and CodeAccessSecurity Elements. The fact that the solution framework does this manipulation during deployment is a great advance so why not using it?
6) For some modification types and in a farm environment the following code won’t propagate your changes across the farm . Mark Wagner has more to tell you.
[CSharp]
SPFarm.Local.Services.GetValue
[/CSharp]
I have also observed this behavior, but I have never been able to find why. This is another dark point I found in SPWebConfigModification class – There is absolutely no explanation whatsoever . I always use the following line of code instead:
[CSharp]
webApp.Farm.Services.GetValue
[/CSharp]
[Update: 6/4/2008] Related Post: https://blogs.devhorizon.com/reza/?p=555
[Update: 4/10/2010] Looks like, the issue 5 is now fixed and you can add and remove assembly and assemblyBindings elements. I haven’t tested it since I wrote this blog post, but some readers left comments below and they said they could add and remove these elements.
Hi Reza,
great post, thanks for taking the time to write it.
Couple questions re: point 4. You say
“I have observed some issues with using EnsureChildNode for adding parent nodes such as appsettings and connectionStrings in MOSS.”
Could you elaborate on this?
Also,
you have a code snippet with the following:
SPWebConfigModification mod = new SPWebConfigModification(”cSection”, “configuration”);
mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureSection;
Is this necessary in a feature receiver where connectionstrings are involved (i.e. in case it doesn’t already exist)?
I haven’t done any development in a long time, so the question might seem silly, but the documentation I can find on this is a bit sparse.
Cheers
Neil
Neil,
No, you are not asking a silly question. It is a very good point. Please look at our feature project at codeplex . I have solved the issue of parent node (connectionstrings) not present when you are adding the child node (specific con string):
https://www.codeplex.com/Release/ProjectReleases.aspx?ProjectName=features&ReleaseId=2502
feature is called Global Web.Config Feature
BTW, EnsureChildNode can not be used to add a section node. You need to use EnsureSectionNode or something like this. The issue is once you add a section , there is no way , you can delete it using the configuration object which is not a biggie. It is just a section with empty content (if you successfully delete all the children) for example “connectionStrings” node
is going to stay in your web.config file forever 🙂
Thank you
You mention that this class cannot be used to add an assembly node. However, I have done that several times with no problem. Why do you think you can’t add an assembly node, or what problems have you experienced there?
I’ve added assembly references as well. Here’s an incomplete, but usable snippet from my app..
private void AddComplationAssemblies(WebConfigUtility webConfigUtility)
{
AddAssemblyReference(“CSI.ESS, Version=1.0.0.0, Culture=neutral, PublicKeyToken=06372373803ae340”,
webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.WebDateChooser.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.Shared.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.WebDataInput.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.WebCombo.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.UltraWebGrid.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
AddAssemblyReference(“Infragistics35.WebUI.WebCombo.v8.2, Version=8.2.20082.1000, Culture=neutral, PublicKeyToken=7DD5C3163F2CD0CB”, webConfigUtility);
}
private void AddAssemblyReference(string strongName, WebConfigUtility webConfigUtility)
{
var path = “configuration/system.web/compilation/assemblies”;
var name = string.Format(“add[@assembly='{0}’]”, strongName);
var value = string.Format(@””, strongName);
webConfigUtility.AddWebConfigModification(name, path, SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode, value, “ESS Comp Assem”);
}
I don’t clearly remember what issue we were facing with adding assemblies into a multi-zone apps and it was pre-SP1. We called CSS and they said that it shouldn’t be used like that.
If you add assemblies within your assemblies section of the web.config then you will not be able to get them out using the WebConfigModifications.Remove method and then applying the WebConfig Modifications. It will most likely add duplicate assembly references within the assemblies section.
Looking at the configuration database, I see that the referenced assembly is deleted using the WebModifications.Remove method along with the ApplyWebConfigModifications, but the web.config entry remains.
I have been doing quite a lot of work around this area for the last 12 months, with lots of success. However, one pet hate that i have with this specific class (SPWebConfigModification) is the inability to set an empty value on an attribute, as the Value property cannot be set to an empty value (disassembled and had a look at the code). We require this to be set on some specific WSS attributes for custom application compabitibility, and having to set a value there causes the web application to break until the text is manually removed from this specific attribute.
Has anyone else had similar experiences with this? If so, does anyone know of any workarounds on how to set an empty value on an attribute using this class?
The other issue or gripe people should be aware of is ensuring that they enter valid values correctly formed – one apostrophe out of place in a value will still be accepted by the class when adding a new configuration node (this is very easy to do when you’re entering a lot of configuration nodes, especially when parsed through XML the way I do it); i’ve found that 9 times out of 10 this is irreversible, so test test test before placing into a production environment (which of course you should be doing anyway) otherwise you may find yourself provisioning a new web application and migrating the site colelctions / configuration over to the new site, and trashing the original web application, as this seems to be the only way to get around the problem of bad configuration.
Is it a “best practice” to make needed modifications to the SharePoint web.config file ONLY through SPWebConfigModification?
– Would it be risky to manually “poke” and change the web.config because SharePoint may decide to generate a new one and over-write the current one sometime in the future?
– Would a 3rd party web part feature installation that also needed to add some custom lines to the web.config file be at risk if it poked the web.config file to add entries rather than using SPWebConfigModification?
Thanks for the clarification…
Yes, because this is the only class the guarantees that your changes will be propagated across the farm and gets cleaned up after you uninstall. SPWebConfigModification is buggy, but still better than manually poking around. If you come up with a manual solution that would give such guarantee, I don’t see a problem of using it. Risk here is the fact that your changes end up in one Web front end server and don’t get cleaned up after you deactivate the respective features. Answer to your last question is no … as long as you don’t mess around with Web.config 🙂
Thank you for writing this article…
After reading the whole thing twice, and then reading the comments, I am at least given some hope as a new MOSS developer that I am not the only one who has some major problems with MOSS related technologies.
It seems there are some major issues with MOSS, and the MOSS development team are just oblivious to certain key things that are wrong with MOSS.
This SPWebConfigModification is just another prime example….
My real pet hate is CAML, basically because its marketed as the ideal way to get data out of MOSS, yet it has no real powerful built in functions, usually meaning you have to extract RAW data into a dataTable, then perform calculations on it. Besides being extremely hard to learn, having hardly any real documentation, the query methods, also require severe work to get less basic tasks to work.
Really wish the MOSS team would stop giving us paffy demonstrations of basic requirements and actually give us tools and ways in MOSS to really get the job done.
Hi!
Is there some workaround concerning the point #3? I really need to change an specified zone web.config file for authentification and I don’t find anyway to do it.
Thanks
Stand alone or farm?
Standalone yes, just use ASP.NET configuration API , but at farm level you need a mechanism to sync other sites as well. You need a timer job to take care of propagation across the farm.
For the moment, it’s standalone… don’t think a Farm will be used.
I’m writing an C# program that do everything I want (create webapp, extend webapp, create site collection, etc…..)
I have some problem using the WebConfigurationManager because i’m not running it from an ASP.NET webpage…
Do you have any sample codes to achieve this?
Tnanks
vIceBerg,
In your case , you need to write a Web Application scoped feature which after you provision your site using your C# app, it is deployed to the newly-provisioned site and in the receiver of the feature you inject the required web.config settings because in that context configuration API is obtainable , but again bear the following in mind:
If you don’t use SPWebConfigModification class and either use ASP.NET 2.0 configuration API or your own mechanism , propagating changes across the farm is YOUR RESPONSIBILITY. If this happens on an standalone installation then you don;t need to be worried about this.
Another question…
I use the following code:
SPWebConfigModification config = new SPWebConfigModification(“add[@name=\”MyConnectionString\”]”, “configuration”);
config.Owner = “Administrator”;
config.Value = “connectionStrings”;
config.Type = EnsureSection;
config.Sequence = 0;
webApp.WebConfigModifications.Add(config);
When doing the webApp.Update() command, I get the following error:
The ‘[‘ character, hexadecimal value 0x5B, cannot be included in a name. Line 1, position 16873.
In your #1 example, you’re doing the exact thing. What do i do wrong?
config.Value = “connectionStrings”;??? How are you passing in the connection string here?
What’s supposed to be in that property? I tried to put an actual value in that and the section don’t get that value.
Slowly, but surely.
I have all my modifications done by SPWebConfigModification.
I’m doing an app to add membership/role provider to a WebApplication. I have to change the WebApp web.config file AND the central administration web.config file.
The changes are OK.
I use the “Mange web.config Modifications” solution of yours. I changed it to be able to choose the central administration webapp from the “Select Web Application” dialog.
When I delete modification from the “normal” WebApplication, everything is removed from the web.config file.
When I delete modification from the central administration webapplication, nothing is done.
I would like to know how should I do my modification in order to be able to delete them using your solution.
Thanks
hi reza,
I am having trouble to update the web.config with custom provide tags.
ModifcationEntry membershipProvider = new ModifcationEntry();
membershipProvider.Name = “membership”;
membershipProvider.Path = “configuration/system.web”;
membershipProvider.Value = “”;
membershipProvider.ModType = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
mods.Add(membershipProvider);
I am creating the entry using above code but its add 2 entries of membership node, one is without default provider attribute and no tag contains inbuilt provider and add tag.
PLease help me out..its urgent.
Thanks
When I make the call to get the SPWebService, I get an XmlException with the message:
“Name cannot begin with the ‘<‘ character, hexadecimal value 0x3C. Line 1, position 2.”
I am seeing this same exception on two different MOSS installations.
Here’s the code:
SPWebApplication curWeb = (SPWebApplication)properties.Feature.Parent;
if ( curWeb != null )
{
// …add mod entries to curWeb.WeConfigModifications…
}
curWeb.Farm.Services.GetValue().ApplyWebConfigModifications();
curWeb.Update();
That second to last line is where the exception occurs. It occurs before the call to ApplyWebConfigModifications.
Any ideas as to what’s going on there?
thankyouu
Anyone have problems with this and .NET20/.NET35 mixed environments? What I mean is one web app is 3.5 and the others are 2.0. We found SPWebConfigModification to throw an error when trying to ApplyWebConfigModifications(). It seems to not like the system.web/pages/controls node when looping through each of the web apps. Anyone seen this behavior?
Actually, you can access assemblyBinding with a little xpath magic:
configuration/runtime/*[local-name()=’assemblyBinding’ and namespace-uri()=’urn:schemas-microsoft-com:asm.v1′]
Credit:
http://blogs.msdn.com/damgaard/archive/2008/01/16/adding-bindingredirects-through-spwebconfigmodification.aspx
@Mike
Thanks Mike!
I have a question: suppose I am adding elements to some xpath say
siteMap/providers
and if suppose this xpath does not exist in web.config, what I did was to create SPWebConfigModification for the entire xpath one by one like created “sitemap” then “provider” and then add the elements I want to that, but when we are dealing with many sites together there are chances that some sites web.cofig may have the xpath siteMap/providers, in this case the existing xpath is getting replaced(overwritten) with the new one I have added, is there any way I can do a check to find if the xpath already exist before adding elements to it.
Thanks
Harish
@harish
i found how to do it ,, just have to add this as EnsureSection, this will make sure that already exisitng nodes are not overriden..
anyway this Q&A was quite usefull
I have added some entries through EnsureSection, i want these entries to be permanently removed.
Please help…..
@Mike
Thank you!
@Reza Alirezaei
Just curious if the element already exist, does the EnsureSection create a node or skipped
Hi,
I am working on enabling the custom master page for the application pages. I have followed posting on this link http://msdn.microsoft.com/en-us/magazine/cc700347.aspx.
Everything works fine except for the addition of Httpmodule to the webconfig. I don’t see any error but the Http module is not getting added to the webconfig file. please let me know if you have any suggestions.
Here is the code I am using
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
namespace Starbucks.SharePoint.ApplicationMaster
{
public class FeatureReceiverWebApplication:SPFeatureReceiver
{
public SPWebConfigModification CreateHttpModuleModification()
{
SPWebConfigModification modification;
string ModName = “add[@name=’SwapApplicationMasterModule’]”;
string ModXPath = “configuration/system.web/httpModules”;
modification = new SPWebConfigModification(ModName, ModXPath);
modification.Owner = “SwapApplicationMaster”;
modification.Sequence = 0;
modification.Type =
SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
modification.Value = @””;
return modification;
}
public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
SPWebApplication WebApp =
(SPWebApplication)properties.Feature.Parent;
WebApp.WebConfigModifications.Add(
CreateHttpModuleModification());
WebApp.WebService.ApplyWebConfigModifications();
WebApp.WebService.Update();
}
public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
{
SPWebApplication WebApp =
(SPWebApplication)properties.Feature.Parent;
WebApp.WebConfigModifications.Remove(
CreateHttpModuleModification());
WebApp.WebService.ApplyWebConfigModifications();
WebApp.WebService.Update();
}
public override void FeatureInstalled(SPFeatureReceiverProperties properties)
{
//throw new NotImplementedException();
}
public override void FeatureUninstalling(SPFeatureReceiverProperties properties)
{
//throw new NotImplementedException();
}
}
}
Thanks in advance,
viji
Best article about this subject. You saved my day. Thanks a lot!
What’s supposed to be in that property? I tried to put an actual value in that and the section don’t get that value.
Thanks for the article.It explains clearly the limitations of the method but you should update it and remove step 5 from yours since you can modify entries in assembly and as well as assembly binding section.
Another shortcoming is that you cannot specify the order in which your modifications appear in the web.config. I regularly use it to register HTTP Modules in the configuration/system.webServer/modules section, but they always get added AFTER the existing SharePoint modules.
Hi Leon,
Not sure if it’ll help in this instance, but try setting the sequence number for your modifications (lowest gets added first)
@Leon Zandman
Sorry should have replied to your commentLeon instead of adding a new comment:
Not sure if it’ll help in this instance, but try setting the sequence number for your modifications (lowest gets added first
I am using this feature for a new sharepoint site
My current environment(farm) has a site which uses the ajax feature and the web.config entries are there in the farm.
I am getting the following error while i activate the feature in PROD,
TEST environment has no issues.
A web configuration modification operation is already running. at
Microsoft.SharePoint.Administration.SPWebService.ApplyWebConfigModifications()
at System.Web.UI.WebControls.Button.OnClick(EventArgs e)
at System.Web.UI.WebControls.Button.RaisePostBackEvent(String eventArgument)
at System.Web.UI.Page.RaisePostBackEvent(IPostBackEventHandler sourceControl, String
eventArgument)
at System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean
includeStagesAfterAsyncPoint)
at Microsoft.SharePoint.WebControls.FeatureActivator.BtnActivateFeature_Click(Object objSender,
EventArgs evtargs)
at Microsoft.SharePoint.SPFeature.DoActivationCallout(Boolean fActivate, Boolean fForce)
at Microsoft.SharePoint.SPFeature.Activate(SPSite siteParent, SPWeb webParent,
SPFeaturePropertyCollection props, Boolean fForce)
at Microsoft.SharePoint.SPAdminFeatureCollection.Add(Guid featid, SPFeaturePropertyCollection
props, Boolean fForce)
at Microsoft.SharePoint.SPFeatureCollection.AddInternal(Guid featureId, SPFeaturePropertyCollection
properties, Boolean force, Boolean fMarkOnly)
at Microsoft.SharePoint.SPFeatureCollection.Add(Guid featureId)
@David – Did u get any resolution to your issue? If yes, could you let me know the fix? Thanks in Advance.
You can apply either Wayne even if you ought to
concentration more on the particular review web page per se.