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.
Important
The running example in this topic uses a console application. Regardless of the type of project, it is critical that you set the correct target .NET Framework and CPU. The project must target Microsoft .NET Framework 3.5 (not Microsoft .NET Framework 4). The target CPU must be either Any CPU or x64. For information about the choice, see How to: Set the Correct Target Framework and CPU. By default, the target CPU is usually x86. To change it, right-click the project name in Solution Explorer, and select Properties. You can change the CPU on the Build tab by using the Platform target drop-down list.
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
Create a console application project in Microsoft Visual Studio and set the target .NET Framework and CPU platform.
Add a reference to the Microsoft.SharePoint.dll to the project. It is in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\ISAPI.
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
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);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);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);