How to: Create and Register or Deregister a Request Classifier

Applies to: SharePoint Foundation 2010

This topic explains how to register and deregister an HTTP request classifier with the Microsoft SharePoint Foundation performance monitoring and HTTP request throttling system.

Persistence of HTTP Request Classifiers

HTTP request classifiers in the HTTP request throttling system persist in the SharePoint Foundation farm’s configuration database as objects of a class that is derived from the SPRequestThrottleClassifier class. These objects are elements in a read-only collection stored as the ThrottleClassifiers property of the SPHttpThrottleSettings object that is itself persisted in the web application’s HttpThrottleSettings property.

To create the Visual Studio solution

1. Create a console application project in Microsoft Visual Studio and set the target .NET Framework and CPU platform.

2. Add a reference to the Microsoft.SharePoint.dll to the project. It is in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI.

3. Open the program.cs file, set an appropriate namespace and class name, and add using statements for Microsoft.SharePoint, Microsoft.SharePoint.Administration, and Microsoft.SharePoint.Utilities namespaces. Your code should now look something like the following.

   using System;
   using Microsoft.SharePoint; 
   using Microsoft.SharePoint.Administration;
   using Microsoft.SharePoint.Utilities;
   
   namespace Contoso.SharePoint.Utilities
   {
       class RequestClassifierRegistrar
       {
           static void Main(string[] args)
           {
   
           }
   // end Main
       }
   }
   

To create and register a request classifier

1. In the Main method, get a reference to the web application, and then get a reference to the throttle settings by calling the GetHttpThrottleSettings(SPPersistedObject) method. The following example shows how.

   Uri webApplicationUri = new Uri("Http://localhost/");
   SPWebApplication webApplication = SPWebApplication.Lookup(webApplicationUri);
   SPHttpThrottleSettings throttleSettings = SPHttpThrottleSettings.GetHttpThrottleSettings(webApplication);
   

2. Still in the Main method, call a constructor for one of the classes that derives from the SPRequestThrottleClassifier class. In this example, the SPHttpFileExtensionThrottleClassifier class is used. Objects of this class classify requests according the file name extension of the requested resource. The constructor for the class takes a String parameter that designates the file name extension (including the leading "." character) and an SPRequestThrottleLevel parameter that specifies the conditions under which the requests for resources with the specified file name extension are throttled. In this example, we specify that requests for ".docx" files are to be blocked whenever the worker process that is servicing the request is in FirstStage throttling mode.

   SPHttpFileExtensionThrottleClassifier docxClassifier = new SPHttpFileExtensionThrottleClassifier(".docx",SPRequestThrottleLevel.FirstStage);
   

3. Still inside the Main method, call the AddThrottleClassifier(SPRequestThrottleClassifier) method, passing your new classifier as the parameter.

   throttleSettings.AddThrottleClassifier(docxClassifier);
   

   Tip

   AddThrottleClassifier(SPRequestThrottleClassifier) throws an ArgumentException if a classifier for the same extension and throttle level already exists. Consider having your code check for the existence of an identical classifier before calling AddThrottleClassifier(SPRequestThrottleClassifier).

   Note

   If there is more than one classifier for the same file name extension, which is possible only if they have different throttle levels, the classifier that has the most stringent throttle level is the effective classifier. For example, if one classifier for .svc resources specifies a throttle level of FirstStage, and another classifier for .svc resources specifies SecondStage, matching requests will be throttled in the first stage. Accordingly, there is no point in having more than one classifier for a given extension.

   There are three other classes in the object model that derive from the SPRequestThrottleClassifier class. See Request Throttling for details. Because these classes use characteristics of HTTP requests other than the file name extension of the resource, it is possible that a given request matches more than one classifier. In that scenario, the request will be throttled or not in accordance with the most stringent classifier. For example, if the request matches a classifier that has a throttle level of FirstStage and it also matches a classifier that has a throttle level of SecondStage, the request is blocked if the worker process is in the first stage of throttling mode.

To deregister a request classifier

• Deregistering a request classifier is similar to registering one, except that your code calls the RemoveThrottleClassifierAt(Int32) method, passing the zero-based index of the classifier in the ThrottleClassifiers collection of the web application’s HttpThrottleSettings property. The code in the following example removes the last classifier.

  Uri webApplicationUri = new Uri("Http://localhost/");
  SPWebApplication webApplication = SPWebApplication.Lookup(webApplicationUri);
  SPHttpThrottleSettings throttleSettings = SPHttpThrottleSettings.GetHttpThrottleSettings(webApplication);
  
  throttleSettings.RemoveThrottleClassifierAt(throttleSettings.ThrottleClassifiers.Count - 1);   
  

See Also

Concepts

Request Throttling