SharePoint - Register an assembly as a safe control in the Web.config file

on Friday, February 19, 2010

In order for you to use your own custom assembly with your web parts and other little bits, you will need to add your safe control to the web.config file.  However, you need to think "WEB FARM" with many servers hosting the web application so I will show you a couple ways to do this.

The entry in the web.config

You need to place a SaveControl element entry into the web.config file of the web application.  The entry looks like the following:

   1: <configuration>

   2:   <SharePoint>

   3:     <SafeControls>

   4:       <SafeControl Assembly="[Assembly Name]" Namespace="[Namespace]" TypeName="*" Safe="True" />

   5:     </SafeControls>

   6:   </SharePoint>

   7: </configuration>
Assembly The name of your assembly needs to added to this section. Although you can simply type the name of the DLL hosting the control into the Assembly element, it is important to not that this is not the recommended practice.  Rather, use a full four part name; i.e. [assembly], version=[version], culture=[culture], publickeytoken=[publickeytoken]Namespace The namespace that your web controls are in.  If you have your controls in multiple namespaces, you will need to add one <SafeContol ...> element for each control.TypeName The name of the web control which is allowed to be executed with the SharePoint web application.  Should your namespace have multiple web controls, you do not need to register each control.  You can simply use * (asterisk) to indicate the dll.Safe A boolean flag, indicating whether the control is treated as safe (true) or unsafe (false). AllowRemoteDesignerA boolean flag, indicating whether the control can be loaded by a remote designer, such as SharePoint Designer.


   1: <SafeControl Assembly="Brett.DemoParts, Version=, Culture=neutral, PublicKeyToken=f03e5f7a44d50a3a" 

   2:              Namespace="Brett.SharePoint.WebParts" 

   3:              TypeName="*" 

   4:              Safe="True" 

   5:              AllowRemoteDesigner="True" />

Methods of updating the web.config file

There are three ways you can update the web.config file,

  • Manually adding the SafeControl to the web.config
  • Adding the SafeControl to the web.config with code
  • Deploy the assembly using a solution package

Manually editing the web.config (bad)

This approach may sound the easiest and quickest way as you simply open up your favourite xml editor, find the <SafeControls> element and add your own control into it.


If you do it this way, you are looking for trouble in a farm as you will need to remember to change the web.config modification for all your servers in the farm as well as all the web applications on the farm that use the custom control.  So should you have a really awsome web part that is used within 5 web applications hosted on your farm of 3 servers, you will need to make the modification to 15 web.config's .. have fun.

Also should you add a new server to your farm, please remember to add the entry the web.config.

Bottom line, this is the worst possible way you can do it  and stay away from doing it this way

Adding the SafeControl to the web.config with code (good)

SharePoint provides a class called SPWebConfigModification which has a set of modification commands in a collection.  These modification commands are applied to the default web.config of the Web Application.  These configuration modification commands will also be added and applied to all servers in a farm.   Finally, should a new server be added to the farm, these modifications will also be applied.

The following code could be added to the FeatureActivated override method in your feature that deploys the web part.

   1: public override void FeatureActivated(SPFeatureReceiverProperties properties) 

   2: {

   3:     // A reference to the features Site Collection

   4:     SPSite site = null;


   6:     // Get a reference to the Site Collection of the feature

   7:     if (properties.Feature is SPWeb)

   8:     { site = ((SPWeb)properties.Feature.Parent).Site; }

   9:     else if (properties.Feature.Parent is SPSite)

  10:     { site = properties.Feature.Parent as SPSite; }


  12:     if (site != null)

  13:     {

  14:         SPWebApplication webApp = site.WebApplication;


  16:         // Create a modification

  17:         SPWebConfigModification mod = new SPWebConfigModification(

  18:             "SafeControl[@Assembly=\"MyAssembly\"][@Namespace=\"My.Namespace\"]"

  19:                 + "[@TypeName=\"*\"][@Safe=\"True\"][@AllowRemoteDesigner=\"True\"]"

  20:             , "/configuration/SharePoint/SafeControls"

  21:             );


  23:         // Add the modification to the collection of modifications

  24:         webApp.WebConfigModifications.Add(mod);


  26:         // Apply the modification

  27:         webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

  28:     }

  29: }

Deploy the assembly using a solution package (best)

The preferred way to provision your features, web parts and assemblies is by creating a Solution Package (.wsp file).  You will add add your assembly, the manifest.xml file and all your other components and resources into the cabinet.

You will need to add the following entry into the manifest.xml

   1: <Solution SolutionId="{1E0FDA58-6611-423a-92EC-8E7355810CEE}"

   2:           xmlns="">

   3:   <FeatureManifests  />

   4:   <ApplicationResourceFiles />

   5:   <CodeAccessSecurity />

   6:   <DwpFiles />

   7:   <Resources />

   8:   <RootFiles />

   9:   <SiteDefinitionManifests />

  10:   <TemplateFiles />


  12:    <Assemblies>

  13:       <Assembly DeploymentTarget="WebApplication" Location="Brett.DemoParts.dll">

  14:          <SafeControls>

  15:             <SafeControl Assembly="Brett.DemoParts, Version=, Culture=neutral, PublicKeyToken=f03e5f7a44d50a3a"

  16:                          Namespace="LitwareWebParts" 

  17:                          TypeName="*" 

  18:                          Safe="True"                         

  19:                          />

  20:          </SafeControls>

  21:       </Assembly>

  22:    </Assemblies>

  23: </Solution>


Key highlights

DeploymentTarget The depoloyment target is location where the assembly will be copied to and can ether be the bin folder of the WebApplication or it could be the GlobalAssemblyCache (GAC)Location The location of the assembly within the cabinet file. SafeControl A SafeControl element entry as described at the beginning of the post.   

Using this method, your assembly will be correctly deployed the servers in the farm as well as added to the safe controls of the web application.  Again any new server added to the farm will automatically get all the solution packages deployed.