Centrally Managed Document Templates

In order to centrally manage a single instance of a document template, the template should be deployed to the _layouts folder.  By mapping a folder for the feature to the layouts folder for your document templates, the template will be deployed to the file system when the solution is deployed, and available to any site collection within the farm. 

1. Setup the content type hub (see https://office.microsoft.com/en-us/sharepoint-server-help/manage-content-type-publishing-HA101631502.aspx).
2. Create a feature that contains a content type with a document template, and the document template itself.  This SharePoint Developer Team Blog describes how to create a content type programmatically, associate a document template, and place the document template under a _layouts subfolder.  
3.  Deploy the feature to the farm.
4. Activate the feature on the content type publishing hub site collection.  Make sure the content type is setup to publish (see site settings->content type gallery, select the content type->Manage publishing for this content type, and make sure it is set to publish.

A couple of caveats. 

• There is a hidden feature for managed metadata featuures on a site collection.  Some site definitions activate, others do not (for example, a blank site will not activate the feature).  See Content type publishing option missing from Site Collection Administration for more information on the feature to activate.  If you don't see a entry in the manage site collection settings for content type publishing then you probably need to activate this feature.
• The solution must be a farm solution since files are deployed to the layouts folder.
• The content type publishing and subscription process is managed by two timer jobs.  Both must run before a content type created on the publishing hub site is present on the subscribing sites. (content type hub, and content type subscriber (one for each web app)

Replicate Document Templates across site collections

If the template is instead deployed to a location within the site collection (for example the default location of _cts/<content type>),  it will be placed within the content database, and the document template will be replicated within each site collection.  For a blog on this approach, see the blog on managing document templates and content types with Office 365, Deploying a Document Template file in Content Type in a (Office365) Sandboxed Solution by Chakkaradeep Chandran.  In the case of a no-code or Office 365 (or a sandboxed solution with an on-premise installation) you will need to deploy document templates to the site collection since you can't write to the file system. 

If the document template is deployed to the default "_cts/<content type>/" location then the document template will be replicated by the content type publishing logic with the content type. Since the document template is replicated, a new document can be created based upon the content type in the subscribing site.  If an updated version of the template is uploaded, then the content type hub will re-publish the content type and document template to all subscribing sites.

Another option is to specify an existing document (which must be a location in the site collection).  If an existing document location is selected, then the content type will be replicated refering to the location in the content type hub.  However creating a new document based upon the content type in this case will fail since the publishing logic will not replicate the template file, and the content type will contain a reference to a document template that doesn't exist in the subscribing site.(unless some other mechanism also replicated this library). 

Conclusion

Generally I'd recommend avoiding using a library to contain the templates if you are using content type publishing.  If you need a central repository and templates don't change often, then use layouts in which case a single copy of the template will be used by all site collections in the farm.  If you can't deploy a farm feature, or you want to manage the templates through the UI rather than with a developed applications, then deploy the template to the default upload location (_cts/<content type>) rather than using a library to contain the templates, and the document template will be replicated by the content type publishing infrastructure.  While I did not test the case of a cross-farm service, you'd clearly need to deploy the feature to all farms when using the layouts approach.  I'd hypothesize that the content hub should still replicate templates in the case where they are stored to _cts location. 

If you want to deploy a content type across a number of site collections without using content publishing (recommended approach is using a site scoped feature), then the _layouts approach is the only solution to make it easy for maintaining a single document template used by all of the site collections  using the content type.

Thanks to Andrew Connell and Rob Bogue for input.

Code Camp - BCS.ppt - The presentation

AssemblyConnectorDemo.completed.zip - the connector implementation

Customer Service and Sales Site.zip - a wsp containing the SharePoint site that is being accessed through the connector, and a zip of the solution implementing the service being accessed by the connector in the demo.

Code Camp Presentation and Demo.zip

Steve Peschka has a bunch of great blogs on claims and SharePoint, including Using the WHR Parameter with SharePoint 2010 and SAML Auth.  In this blog Steve describes how to use a http module  in a SharePoint environment  to insert a whr parameter based upon some decision logic.  This insertion onto the url  occurs when SharePoint recognizes the user is not authenticated, and goes through a series of redirects to a trusted claims provider to perform authentication.  This solves the second, more sophisticated approach for using whr described in previously mentioned article.   This approach also requires that you write custom logic and maintain that logic for selecting the authentication provider.

Ideally SharePoint would just work with the first approach as well, which supports directly appending the whr parameter onto the SharePoint url you are attempting to access.  Building off of Steve's blog, an example url accessing SharePoint may look like  https://www.vbtoys.com/?whr=https://geneva.vbtoys.com/adfs/services/trust.   The advantage of this approach is that it would not require the implementation of custom logic.  Unfortunately SharePoint doesn't carry over the whr parameter from an incoming url over to the redirect url to the federation server.  So it won't work.  This approach is simpler but less powerful than the approach described by Steve.  Using Steve's approach I'm not tied to a particular url.  Rather any url I attempt to access in SharePoint that is being redirected to the federation server will have the whr inserted.  But often customers don't want to write custom code, and the benefit of the simpler approach is that I can just hand out different urls for users to bookmark that will do the pre-selection for them.  For example, if I had an extranet site for partners, I could hand out urls to the partners with the appropriate identity provider pre-selected for that partner.

There is simple implementation to carry the url over from the original SharePoint url.  Extending from Steve's blog, instead of processing the begin request, process the end request event.  In the end request event, check for the whr parameter on the request, and if it is present on the request, but not present on the redirect url, then add it.  It's pretty much that simple.  Below is example code:

public void EndRequest(object sender, EventArgs e)
{
    try
    {
        //get the app and context sources
        HttpApplication application = (HttpApplication)sender;
        HttpContext context = application.Context;

        if (context.Response.IsRequestBeingRedirected == true &&
            context.Request.QueryString.AllKeys.Contains("whr"))
        {
            string whr = "whr=" + context.Request.QueryString["whr"];
            string redir = context.Response.RedirectLocation;
            if (!redir.Contains(whr))
            {
                redir = redir + (redir.Contains("?") ? "&" + whr : "?" + whr);
                context.Response.RedirectLocation = redir;
            }
        }
    }
    catch(Exception ex)
    {
        Debug.WriteLine(ex.Message);
    }
}

I've attached a modified version of the project from Steve's original blog post that implements this approach.  This is only a sample.  I'd definitely take time to make it a bit more robust for a production implementation.  Also I've put in some pre and post build steps to automatically register and unregister the assembly from the gac - if things aren't working, then the exe referenced may be in a different location.  Finally make sure you follow the instructions in the project.  Steve's original instructions still hold.

Hope this helps.

AdfsHrd.zip

SharePoint Guidance 2010 Hands On Lab has just been released to CodePlex. It consists of six labs: one for logging, one for service location, and four for application setting manager. Each lab takes about 20 minutes to walk through. Interested people please try one of those labs to give me feedback. Each lab consists of a PDF document. You can go through the steps in the doc to create solution and then build/deploy the solution and run the lab. For those of you who wants to save time, we included the final solution so you can just build/deploy the solution and run the lab.

For the next a few weeks, we are going to add two more labs: Logging for sandbox and installation-uninstallation of Service Locator in a Farm environment. That should cover all the basic scenarios for the SPG2010 reusables

Since the service locator is called frequently to load types, the information mapping an interface to a type is cached in memory by the locator for both the farm and site collection level mappings.  By default the site collection mappings are purged every minute (this is configurable) and the type mappings for the farm are not purged from the cache.  If new type mappings are defined, then IIS must be reset to flush this cache.  However the service locator also has a method, Reset, that will cause the cached values to be reset.  We wanted to get a feature into the service locator to purge the cache and re-lookup the cached values when a type mapping can't be located, but unfortunately we ran out of time to get this feature implemented.  The good news is that its relatively straightforward to create a wrapper class that will do this for you.

 public class ServiceLocatorWrapper
{
    public static TService GetInstance<TService>()
    {
        TService instance;

        try
        {
            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>();
        }

        catch (ActivationException e)
        {
            LogFailure<TService>(e);
            SharePointServiceLocator.Reset();
            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>();
        }

        return instance;
    }


    private static void LogFailure<TService>(Exception e)
    {
        ILogger logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();
        logger.TraceToDeveloper(e, string.Format("Failed to load type {0}, flushing service locator and retrying", typeof(TService).Name));
    }
}

 The wrapper class implements a generic method for getting a type instance.  The generic method just passes this through to service locator to create the instance.  The wrapper also catches an ActivationException when thrown, which is thrown by the service locator if it can't find a type mapping.  When this exception occurs, the wrapper invokes the Reset method which purges the cached settings, the re-attempts creating the instance.  Since the mappings have been purged the settings are re-read from configuration and cached.  Therefore any added type mappings will be picked up.

I'd highly recommend using this wrapper approach to improve robustness if you are using the SharePointServiceLocator.

The wrapper class can add a few additonal similar methods to handle all of the different ways service locator can create instances as the following code demonstrates.

public class ServiceLocatorWrapper

{

    public static TService GetInstance<TService>()

    {

        TService instance;



        try

        {

            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>();

        }

        catch (ActivationException e)

        {

            LogFailure<TService>(e);

            SharePointServiceLocator.Reset();

            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>();

        }



        return instance;

    }



    public static TService GetInstance<TService>(string key)

    {

        TService instance;



        try

        {

            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>(key);

        }

        catch (ActivationException e)

        {

            LogFailure<TService>(e);

                SharePointServiceLocator.Reset();

            instance = SharePointServiceLocator.GetCurrent().GetInstance<TService>(key);

        }



        return instance;

    }



    public static TService GetInstance<TService>(SPSite site)

    {

        TService instance;



        try

        {

            instance = SharePointServiceLocator.GetCurrent(site).GetInstance<TService>();

        }

        catch (ActivationException e)

        {

            LogFailure<TService>(e);

            SharePointServiceLocator.Reset();

            instance = SharePointServiceLocator.GetCurrent(site).GetInstance<TService>();

        }



        return instance;

    }



    public static TService GetInstance<TService>(SPSite site, string key)

    {

        TService instance;



        try

        {

            instance = SharePointServiceLocator.GetCurrent(site).GetInstance<TService>(key);

        }

        catch (ActivationException e)

        {

            LogFailure<TService>(e);

            SharePointServiceLocator.Reset();

            instance = SharePointServiceLocator.GetCurrent(site).GetInstance<TService>(key);

        }



        return instance;

    }



    private static void LogFailure<TService>(Exception e)

    {

        ILogger logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();

        logger.TraceToDeveloper(e, string.Format("Failed to load type {0}, flushing service locator and retrying", typeof(TService).Name));

    }

}

Creating the timer job

Sometimes you need to deploy settings to every web front end, or have a piece of code execute on every web front end.  Your choices in SharePoint are to either have an administrator run a script on each front end, or use a timer job.  This blog post describes how to use a timer job to accomplish this. 

When you log to the event log using the native event log APIs or using the new SharePoint 2010 logging capabilities the event source used for the event logged must already exist, or the code must be running in a context that has privileges to create the event source, which means permissions to write to the registry.  If the code doesn't have those permissions, then a security exception will be thrown.  This condition may also show up as an security exception for attempting to access logs to which you don't have access.  This may occur as the Event Log searches for the event source registration in different event logs, in particular the security log, to which your code may also not have access to.  In any case, if you are attempting to log an event using the SharePoint 2010 APIs and are receiving a security exception, there is a good chance that the event source being used hasn't been created on the machine.  Since event sources require registration in the local machine registry, the registration process must take place on each physical machine (i.e., code must run in a high privileged account on each WFE to register the event sources).

I'll state the obvious first.  The timer job must be running under an account that can write to the registry.  The timer job runs under the managed account called "farm account", and its pretty common to make this a relatively high permission account.  By default it is running as NETWORK SERVICE, and NETWORK SERVICE will not have permission to write the settings to the registry, and therefore the process described in this blog will not work with default settings.  This obvious one got me when I first developed this solution.  You can added managed accounts in central admin->security->configure managed accounts, and you can set the farm account in central admin->security->configure service accounts.

There are two components that need to be developed; the timer job, and a feature to activate the timer job.  We'll start with the timer job.  A SharePoint timer job runs under a SharePoint managed process for timer execution (OWSTimer.exe, SharePoint 2010 Timer service).  Timers run as one might expect periodically.  The timer jobs that are scheduled, and the intervals at which they run are described here: https://technet.microsoft.com/en-us/library/cc678870.aspx.  The type of timer job we'll create for this particular task will run only once, but will run on every web front end.

This example implementation uses the patterns and practices SharePoint Guidance Library that can be downloaded from https://www.microsoft.com/spg. 

The following listing shows the full source code for the timer job:

   1: using System;

   2: using System.Collections.Generic;

   3: using System.Linq;

   4: using System.Text;

   5: using Microsoft.SharePoint.Administration;

   6: using Microsoft.Practices.SharePoint.Common.Logging;

   7: using Microsoft.SharePoint;

   8: using Microsoft.Practices.SharePoint.Common.ServiceLocation;

   9:  

  10: namespace CreateEventSourcesJob

  11: {

  12:     /// <summary>

  13:     /// This class defines a timer job that will run on each WFE once.  The timer job will create the event 

  14:     /// sources for the logger if the event sources do not already exist.  Note that the account the timer 

  15:     /// job runs under must have sufficient permissions to write to the registry.  The default account 

  16:     /// is NetworkService, which does not have permission to write to the directory.  This account is 

  17:     /// changed through central admin.  You will first need to create a managed account 

  18:     /// (CentralAdmin->Security->Configure Managed Accounts) with an account that has sufficent permission.

  19:     /// You then assign the account (CentralAdmin->Security->Configure Service Accounts) to the Farm Account, 

  20:     /// which is used by the timer.  At this point this task will work.

  21:     /// </summary>

  22:     public class CreateLoggingEventSourceJob: SPJobDefinition

  23:     {

  24:         public static string JobName { get { return "CreateLoggingEventSources"; } }

  25:         public static string JobTitle { get { return "Create Logging Event Sources"; } }

  26:  

  27:         /// <summary>

  28:         /// Creates the job instance

  29:         /// </summary>

  30:         public CreateLoggingEventSourceJob()

  31:             : base(JobName, SPFarm.Local.TimerService, null, SPJobLockType.None)

  32:         {

  33:         }

  34:  

  35:         /// <summary>

  36:         /// A description of the job being ran

  37:         /// </summary>

  38:         public override string Description

  39:         {

  40:             get

  41:             {

  42:                 return "Registers the event sources on WFE's for patterns and practices Logger";

  43:             }

  44:         }

  45:  

  46:         /// <summary>

  47:         /// The name to display for the job.

  48:         /// </summary>

  49:         public override string DisplayName

  50:         {

  51:             get

  52:             {

  53:                 return "patterns and practices Event Source Registration job";

  54:             }

  55:         }

  56:  

  57:         /// <summary>

  58:         /// Called by SharePoint when this job is ran.  This is where the work is done, whihc is simply

  59:         /// calling EnsureConfiguredAreasRegistered.  This method reads the areas from configuration, and

  60:         /// creates an event source for each if it doesn't exist.  It will also create the event source

  61:         /// for the default category if it does not exist.

  62:         /// </summary>

  63:         /// <param name="targetInstance">The target instance IDfor the job</param>

  64:         public override void Execute(Guid targetInstance)

  65:         {

  66:             try

  67:             {

  68:                 DiagnosticsAreaEventSource.EnsureConfiguredAreasRegistered();

  69:             }

  70:             catch (Exception e)

  71:             {

  72:                 var logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();

  73:                 logger.TraceToDeveloper(e);

  74:                 logger.LogToOperations(e.ToString() + " INNER EXCEPTION: e.InnerException.ToString()", 

  75:                     EventSeverity.ErrorCritical);

  76:                 throw;

  77:             }

  78:         }

  79:  

  80:         /// <summary>

  81:         /// This method sets up the timer to fire.  This is the method after the logging categories are 

  82:         /// setup that an application can call to register the event sources.

  83:         /// </summary>

  84:         public static void ScheduleJob()

  85:         {

  86:             CleanUpJobs(SPFarm.Local.TimerService.JobDefinitions);

  87:             var job = new CreateLoggingEventSourceJob();

  88:             job.Schedule = new SPOneTimeSchedule(DateTime.Now);

  89:              job.Update();

  90:         }

  91:  

  92:         /// <summary>

  93:         /// Cleans up and old versions found of the job.

  94:         /// </summary>

  95:         /// <param name="jobs">The job list.</param>

  96:         private static void CleanUpJobs(SPJobDefinitionCollection jobs)

  97:         {

  98:             foreach (SPJobDefinition job in jobs)

  99:             {

 100:                 if (job.Name.Equals(CreateLoggingEventSourceJob.JobName,

 101:                                         StringComparison.OrdinalIgnoreCase))

 102:                 {

 103:                     job.Delete();

 104:                 }

 105:             }

 106:         }

 107:     }

 108: }

We’ll take a look now at specific portions of the timer job.  First every timer job will derive from SPJobDefinition.  When the timer job is constructed, the base class is initialized with a few parameters:

• JobName – the name of our job.
• SPFarm.Logal.TimerService – We need to associate either a service or a web application with the timer job we want to run.  In this case we specify the the timer service as the associated service.
• null – this specifies the SharePoint server to run the job on.  By specifying null it will be ran on all servers.
• SPJobLockType.None – this isn’t obvious, but by defining a lock job type of none, we are telling SharePoint to run this on every machine.  For more information, see https://msdn.microsoft.com/en-us/library/microsoft.sharepoint.administration.spjoblocktype.aspx.

There are two other interesting pieces to the timer job.  First we need to schedule the job to run.  The class provides a convenience function to schedule this timer job for code that has registered a new logging category for the logger to use.  The convenience function is a static function that registers an instance of the timer to execute.  The timer is a single shot timer that will only run once.  It is scheduled to run immediately with the timer service.

   1: /// <summary>

   2: /// This method sets up the timer to fire.  This is the method after the logging categories are 

   3: /// setup that an application can call to register the event sources.

   4: /// </summary>

   5: public static void ScheduleJob()

   6: {

   7:     CleanUpJobs(SPFarm.Local.TimerService.JobDefinitions);

   8:     var job = new CreateLoggingEventSourceJob();

   9:     job.Schedule = new SPOneTimeSchedule(DateTime.Now);

  10:      job.Update();

  11: }

When the job is registered we need to clean up any previous jobs otherwise the job will fail due to a duplicate definition. CleanUpJobs will clean out any previous instances for us before the current job is scheduled.  CleanupJobs will construct an instance of the job, so you can’t do this logic easily in the constructor, rather it’s done before the timer is rescheduled as shown above.

   1: /// <summary>

   2: /// Cleans up and old versions found of the job.

   3: /// </summary>

   4: /// <param name="jobs">The job list.</param>

   5: private void CleanUpJobs(SPJobDefinitionCollection jobs)

   6: {

   7:     foreach (SPJobDefinition job in jobs)

   8:     {

   9:         if (job.Name.Equals(CreateLoggingEventSourceJob.JobName,

  10:                                 StringComparison.OrdinalIgnoreCase))

  11:         {

  12:             job.Delete();

  13:         }

  14:     }

  15: }

The final piece is where the work is actually done.  The timer will construct this class to run the job, then call the Execute method.  The work is actually done in the Execute method.

   1: /// <summary>

   2: /// Called by SharePoint when this job is ran.  This is where the work is done, whihc is simply

   3: /// calling EnsureConfiguredAreasRegistered.  This method reads the areas from configuration, and

   4: /// creates an event source for each if it doesn't exist.  It will also create the event source

   5: /// for the default category if it does not exist.

   6: /// </summary>

   7: /// <param name="targetInstance">The target instance IDfor the job</param>

   8: public override void Execute(Guid targetInstance)

   9: {

  10:     try

  11:     {

  12:         DiagnosticsAreaEventSource.EnsureConfiguredAreasRegistered();

  13:     }

  14:     catch (Exception e)

  15:     {

  16:         var logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();

  17:         logger.TraceToDeveloper(e);

  18:         logger.LogToOperations(e.ToString() + " INNER EXCEPTION: e.InnerException.ToString()", 

  19:             EventSeverity.ErrorCritical);

  20:         throw;

  21:     }

  22: }

In this method, a convenience method is called in the SharePoint Guidance Library that will read all of the diagnostic areas, and register an event source for each (SharePoint logging has diagnostic areas, and each diagnostic area has one or more diagnostic category.  An example of a diagnostic area would be search or taxonomy).  The following code is provided by the guidance library – if you had your own implementation based upon the SPDiagnosticsServiceBase class, you would need to implement similar logic:

   1: /// <summary>

   2:  /// Ensures that all configured DiagnosticAreas are registered as event sources.

   3:  /// </summary>

   4:  [SharePointPermission(SecurityAction.InheritanceDemand, ObjectModel = true)]

   5:  [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]

   6:  public static void EnsureConfiguredAreasRegistered()

   7:  {

   8:      var mgr = SharePointServiceLocator.GetCurrent().GetInstance<IConfigManager>();

   9:      var areas = new DiagnosticsAreaCollection(mgr);

  10:      RegisterAreas(areas);

  11:  }

  12:  

  13:  /// <summary>

  14:  /// Takes all the configured areas and set them as event sources.

  15:  /// </summary>

  17:  public static void RegisterAreas(DiagnosticsAreaCollection areas)

  18:  {

  19:      Validation.ArgumentNotNull(areas, "areas");

  20:  

  21:      foreach (DiagnosticsArea area in areas)

  22:      {

  23:          if (!EventLog.SourceExists(area.Name))

  24:          {

  25:              EventLog.CreateEventSource(area.Name, Constants.EventLogName);

  26:          }

  27:      }

  28:  

  29:      if (!EventLog.SourceExists(DiagnosticsArea.DefaultSPDiagnosticsArea.Name))

  30:      {

  31:          EventLog.CreateEventSource(DiagnosticsArea.DefaultSPDiagnosticsArea.Name, Constants.EventLogName);

  32:      }

  33:  }

At this point all of the logic has been demonstrated for registering the events. 

Registering Diagnostic Areas and Categories with SharePoint Logger

The SharePointLogger supports adding new diagnostic areas and categories through configuration rather than implementation.  Typically this will be done through a feature receiver.  These configuration values are stored using the ConfigurationManager in farm level configuration.  SharePoint prevents writing to Farm Level configuration from a content web.  FeatureActivated for site and web scoped features will run in the context of the content web (unless activated from powershell/stsadm).  Therefore you should not register this information in the FeatureActivated event of a web or site scoped feature.  There are two approaches that can be taken. 

• The first, and recommended approach is to scope the feature as Farm.  Since the configuration settings apply across the farm, its reasonable to use a farm scoped feature to set the values.  A farm scoped feature will run at a sufficiently high permission level, outside of the content web, to write to farm level configuration.  In the case of a farm scoped feature, the logic may either be in the FeatureActivated or FeatureInstalled event, and by default SharePoint will activate a farm scoped feature when it is installed. 
• The second choice is to put the logic in the FeatureInstalled event of a Site or Web scoped feature.  This method is less preferred, but still reasonable since the feature must be deactivated on all webs or sites in the farm before it can be removed. 

The following example shows how to register the events from a farm scoped event receiver:

   1: public override void FeatureActivated(SPFeatureReceiverProperties properties)

   2: {

   3:     var mgr = SharePointServiceLocator.GetCurrent().GetInstance<IConfigManager>();

   4:     DiagnosticsAreaCollection areas = new DiagnosticsAreaCollection(mgr);

   5:  

   6:  

   7:     if (areas["loonytunes"] == null)

   8:     {

   9:         var area = new DiagnosticsArea("loonytunes");

  10:         area.DiagnosticsCategories.Add(new DiagnosticsCategory("bugs bunny"));

  11:         areas.Add(area);

  12:         areas.SaveConfiguration();

  13:     }

  14:     CreateLoggingEventSourceJob.ScheduleJob();

  15: }

In this example the areas are added for the logger, and then the job is scheduled to create the event sources.

One more caution.  The timer will tend to lock the assembly.  You should recycle the timer service whenever you are rebuilding to ensure the assembly isn’t locked and therefore not updated in the GAC.

I have attached the full source as well.  Hope this is helpful.

CreateEventSourcesJob.zip

Updated: Debugging Feature Activated - so I said below that debugging feature activated is easy, which is true especially for site and web scoped features, but may not be obvious if you haven't done it before.  To debug FeatureActivated,

1)      Properties->SharePoint, change Active Deployment Configuration to No Activation

2)      Start the project in the debugger.

3)      Activate the feature through site settings (assuming it’s a site or web scoped feature).

Original Post

Recently I had some code that I had to put in feature installed.  Debugging FeatureActivated is no problem in VS2010, but FeatureInstalled isn't so simple.  The feature installed event gets fired when a feature is installed to the farm.  It runs under a higher security context than feature activate, therefore you can do things like write settings to the farm or web application.  In my case my feature installed code had a bug, but I wasn't sure how I could hook it.  I found one approach at least that did work, so I figured I'd blog about it.

There are three possibilities for debugging the FeatureInstalled (this is for a Farm Solution):

1. The FeatureInstalled is throwing an exception and deploy fails in VS.  It's OK that the FeatureInstalled ran partially, and you can rerun to debug.

2. The FeatureInstalled is not throwing an exception, but its OK that it ran once and you can run it again.

3. You can't have the FeatureInstalled event run partially or completely prior to debugging.

The first 2 cases are actually pretty simple.  First deploy the project from VS.  This will put everything in the right place, even if an exception is thrown in your FeatureInstalled, and it looks like the deploy failed.  Then follow the following process.

One way that features are commonly installed is from the command line using STSADM or powershell.  You can use this to hook into the debugging process.  In this case I will use the "TestFarmSettings" project as an example.  I did the following in order to debug the feature installed:

1.  Added a command line project to my solution.
   1. set build, platform target to any cpu (under build tab), and set project to the 3.5 framework (under application tab)
   2. On the debug tab, set start external program, and set the external program to "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\BIN\stsadm.EXE"
   3. Add a reference to my sharepoint project that has the feature installed you want to debug.
2. Set the breakpoint on myFeatureInstalled event handler.
3. Deploy the SharePoint project from VS.  It is OK if the deploy fails due to an exception thrown in the feature receiver.
4. Add the following for the command line options for the console application in the debug tab: -o installfeature -filename <your feature name>\feature.xml -force.  For example, I used -o installfeature -filename TestFarmSettingStore_Feature1\feature.xml -force. 
5. Set the console application as the startup project
6. Hit F5.  Your breakpoint will be hit.

Case 3 its more complicated since you need to get the files into the right places yourself.  As a little background, the reason why you run the deploy is to get the solution added and installed, and get the debug information deployed for the gac'd assembly.  If you do the add and install solution methods manually, then run the debug files don't get into the right place for the assembly. 

You will need to run some manual steps to setup the conditions:

1. You will need to add the solution, which should be in the debug\bin output of your project.  stsadm.exe is located in "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\BIN\".
2. Add the solution, for example stsadm -o addsolution -filename TestFarmSettingStore.wsp
3. Deploy the solution, for example, >stsadm -o deploysolution -name testfarmsettingstore.wsp -url https://localhost -immediate -allowGacDeployment

Now you are ready to actually install a feature. Remember that by default farm and web app scoped features will install automatically when the deploy solution step is ran, and so you will need to change this behavior for those solution types.  This is controlled by the ActivateOnDefault property for the feature (see Feature Element (Feature))

You will need to copy the debug file (.pdb) into the location that your gac'd assembly gets installed.  You can find that location by running dir /s c:\windows\assembly\<your assembly name>.dll.   Once the debug file is located beside the assembly, you can then perform the steps outlined with the console app.  You will be able to break on the FeatureInstalled event the first time you run it.

 If anyone has an easier way, please let me know!

You can add a page to central administration and add an entry to the central administration menu to manage application settings for the farm or web application.  As I reviewed in my previous post, Using the Applications Setting Manager with Web App Config (Developing Applications for SharePoint 2010), the settings for a farm or web application cannot be written to from a content web.  However they can be written to from a page hosted in central administration.  For information on how to add a page and the menu entry to central admin, see How to: Deploy an Application Page to Central Administration.

Once the page is deployed, you'll need to actually add the code to update the settings to central admin.  This example demonstrates a simple interface for configuring settings.  One thing I found is that when developing a page for central admin, you'll often need to reset IIS between each debugging session since it appears things are being cached.  I'd start off getting the administration page visible following the above how-to, and then you can perform the following to actually build out updating settings.

The page I built is pretty simple.  It updates a single known setting as described below:

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">

            Select Web App:<asp:DropDownList ID="DDWebApplications" runat="server" />

            <br />Enter Setting Value:

            <asp:TextBox ID="TextBoxSettingValue" runat="server"></asp:TextBox>    

            <asp:Button Text="Save" ID="ButtonSave" runat="server" OnClick="OnSave" />

</asp:Content>

The approach I'll outline works well for simple types.  The application setting manager can also store serialized complex types.  In order to administer these you will need to be able to load the assembly that contains the classes so they can be properly serialized and deserialized.  This post won't go into that detail.

As you can see, I'm a master of UI from the following screen shot of my custom page:

Often the value you want to set is on a content web application.  The dropdown list is populated when the page is loaded:

protected void Page_Load(object sender, EventArgs e)

{

    if (!IsPostBack)

    {

        SetWebApps();

    }

}



 

protected void SetWebApps()

{

    DDWebApplications.Items.Clear();



    var names = new List<string>();

    var ids = new List<Guid>();



    foreach (SPWebApplication webApp in SPWebService.ContentService.WebApplications)

    {
        DDWebApplications.Items.Add(new ListItem(webApp.Name, webApp.Id.ToString()));

    }

}



 

In order to set the value, a user selects the content web they want to set the value for, then enters the value and saves.  The save logic is pretty simple:

protected void OnSave(object sender, EventArgs args)

{

    try

    {

        var locator = SharePointServiceLocator.GetCurrent();

        var configMgr = locator.GetInstance<IConfigManager>();

        string id = DDWebApplications.SelectedValue;

        var webApp = SPWebService.ContentService.WebApplications[new Guid(id)];



        IPropertyBag bag = new SPWebAppPropertyBag(webApp);

        int valueToSet = int.Parse(TextBoxSettingValue.Text);



        configMgr.SetInPropertyBag(settingName, valueToSet, bag);

    }

    catch (Exception ex)

    {

        SharePointServiceLocator.GetCurrent().GetInstance<ILogger>().LogToOperations(ex);

    }

}

First the code gets the web app ID from the drop down list, creates an instance of that web app, and then creates a property bag based upon the web app.  Under the covers, the property bag uses a SPPersistedObject derived class called WebAppSettingStore to store settings in.  An instance of this class is a child of the web application.  If the persisted doesn't exist and can't be loaded, then one is created and saved when the property bag is constructed.  The setting value is then simply set into the property bag, which will under the covers store the value in the WebAppSettingStore instance.

That's it for building custom properties.  Of course typically there are more settings, and they are more complex to manage, but this blog provides all of the pieces in terms of creating the admin page, getting the objects, and storing the objects.

Explanation 

Web application and Farm settings can't be written from a content web application.  A security exception will be thrown when writing to either of these locations a content web site.  A content web site is essentially sites that end users access, either internally or externally, and will typically be most of the web apps in your farm.  This security feature ensures that settings at these levels can't be compromised due to a security flaw on a page being displayed to end users.  Settings at these levels can be read without any issues. 

The SharePoint Guidance Library included in the Developing Applications for SharePoint 2010 includes an Application Settings Manager that can read and write settings at different levels, including the farm and the web application.  The application settings manager classes help manage settings, and provide a feature for hierarchical lookup of settings (web->site->web application->farm).  At the web application and farm levels the application settings manager uses a class derived from SPPersistedObject that is a child of the farm or web application.  For more info on the design you can see the Application Settings Manager detailed documentation. 

Since these classes are a child of the web application or farm, the same security rules apply to them as apply to the parent object.  Therefore you can't write the settings to  the farm level or the web app level from a web part hosted in a content web app.  I wrote a quick spike to demonstrate. 

Here is a simple web part:

The code that is behind both of these buttons is as follows: 

protected void OnWriteWebAppSettings(object sender, EventArgs e)

{

    var locator = SharePointServiceLocator.GetCurrent();

    var configMgr = locator.GetInstance<IConfigManager>();



    var webAppPropBag = configMgr.GetPropertyBag(ConfigLevel.CurrentSPWebApplication);

    var setting = 1;

    configMgr.SetInPropertyBag(settingName, setting, webAppPropBag);

    LiteralResults.Text = "saved setting: " + settingName + " Value: '" + setting + "'";

}



protected void OnReadWebAppSettings(object sender, EventArgs e)

{

    ReadWebAppSettings();

}



protected void ReadWebAppSettings()

{

    var locator = SharePointServiceLocator.GetCurrent();

    var configMgr = locator.GetInstance<IConfigManager>();



    var webAppPropBag = configMgr.GetPropertyBag(ConfigLevel.CurrentSPWebApplication);

    var setting = 1;

    setting = configMgr.GetFromPropertyBag<int>(settingName, webAppPropBag);

    LiteralResults.Text = "retrieved setting: " + settingName + " Value: '" + setting + "'";

}

When the read button is pressed, then a value of 0 is returned (in this case the value has not been defined, and 0 is the default value for an integer, which is returned since the setting is not defined.  For a complex object, a null would be returned instead).  When the write button is pressed, then a security exception is thrown:

System.Security.SecurityException was caught

  Message=Access denied.

  Source=Microsoft.SharePoint

  StackTrace:

       at Microsoft.SharePoint.Administration.SPPersistedObject.BaseUpdate()

       at Microsoft.Practices.SharePoint.Common.Configuration.SPWebAppPropertyBag.set_Item(String key, String value)

       at Microsoft.Practices.SharePoint.Common.Configuration.ConfigManager.SetInPropertyBag(String key, Object value, IPropertyBag propertyBag)

  InnerException: 

You can see that when the update is attempted, a security exception gets thrown.  This exception will be re-thrown by the ConfigManager as a ConfigurationException. 

 Option 1: Add/Update the values in a feature receiver

One way to address this is to update or set any values in a feature receiver.  If you deploy this as a site or web scoped feature, then there is some special handling involved.  A site or web scoped feature is activated from a content web site.  Therefore if you put the logic into the FeatureActivated event, you will again get a security exception.  You can put this logic instead into the FeatureInstalled event.  FeatureInstalled gets fired when the feature is installed, which typically occurs through a higher privileged account like the command line, or a timer service.  However FeatureInstalled has another issue you'll need to contend with.  There is no site or web context passed into the FeatureInstalled event (since at installation it's not being associated to a web or site - that happens when the feature is activated).  As a result you will need to generate the site context yourself as in the following example:

public override void FeatureInstalled(SPFeatureReceiverProperties properties)

{

    var locator = SharePointServiceLocator.GetCurrent();

    var configMgr = locator.GetInstance<IConfigManager>();



    using (SPSite site = new SPSite("https://localhost/sites/test"))

    {

        configMgr.SetWeb(site.RootWeb);

        var webAppPropBag = configMgr.GetPropertyBag(ConfigLevel.CurrentSPWebApplication);

        var setting = 1;

        configMgr.SetInPropertyBag(settingName, setting, webAppPropBag);

    }

}

In general though its best to deploy a setting at the same level it is stored if you are deploying with a feature.  This way you can be assured that the feature is only installed/activated once at the appropriate scope, and don't need to worry about conflicts or reference counting (if for example you figured out a way to set the web application setting in a site FeatureActivated event, then how do you decide when to remove it since the feature may have been activated muliple times within the web application?).  If you deploy this instead as a web application feature, then you can write and remove the setting in the FeatureActivated/FeatureDeactivating code since a web app feature can't be activated from a content web app.  The below example shows a FeatureActivated and FeatureDeactivating code for a web application scoped feature for adding settings to the web application.  Remember that web application scoped features are automatically activated and deactivated by default when a feature is installed/uninstalled.  This behavior is controlled by the attribute ActivateOnDefault on the Feature element.

public override void FeatureActivated(SPFeatureReceiverProperties properties)

{

    var locator = SharePointServiceLocator.GetCurrent();

    var configMgr = locator.GetInstance<IConfigManager>();

    SPWebApplication webapp = properties.Feature.Parent as SPWebApplication;

    IPropertyBag bag = new SPWebAppPropertyBag(webapp);



    configMgr.SetInPropertyBag(settingName, 2, bag);

}







public override void FeatureDeactivating(SPFeatureReceiverProperties properties)

{

    var locator = SharePointServiceLocator.GetCurrent();

    var configMgr = locator.GetInstance<IConfigManager>();

    SPWebApplication webapp = properties.Feature.Parent as SPWebApplication; 

    IPropertyBag bag = new SPWebAppPropertyBag(webapp);



    configMgr.RemoveKeyFromPropertyBag(settingName, bag);

}

 Option 2: Add a configuration page to central admin

 Central admin runs in a different application pool from the content web apps.  From central admin you have permissions to change any farm or web app level setting.  A how-to provide in the guidence describes the task of adding a custom page to central admin called How to: Deploy an Application Page to Central Administration.  In my next post I will walk through a simple example page for editing web application settings in central admin.