Custom Headers <customHeaders>

Overview

The <customHeaders> element of the <httpProtocol> element specifies custom HTTP headers that Internet Information Services (IIS) 7 will return in HTTP responses from the Web server.

Note: HTTP headers are name and value pairs that are returned in responses from a Web server. Custom response headers are sent to the client together with the default HTTP header. Unlike redirect response headers, which are returned in responses only when redirection occurs, custom response headers are returned in every response.

Compatibility

Version Notes
IIS 8.5 The <customHeaders> element was not modified in IIS 8.5.
IIS 8.0 The <customHeaders> element was not modified in IIS 8.0.
IIS 7.5 The <customHeaders> element was not modified in IIS 7.5.
IIS 7.0 The <customHeaders> element of the <httpProtocol> element was introduced in IIS 7.0.
IIS 6.0 The <customHeaders> element replaces the IIS 6.0 HttpCustomHeaders metabase object.

Setup

The <customHeaders> element of the <httpProtocol> element is included in the default installation of IIS 7.

How To

How to set custom HTTP headers for a Web site or application

  1. Open Internet Information Services (IIS) Manager:
    • If you are using Windows Server 2012 or Windows Server 2012 R2:
      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
    • If you are using Windows 8 or Windows 8.1:
      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
    • If you are using Windows Server 2008 or Windows Server 2008 R2:
      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
    • If you are using Windows Vista or Windows 7:
      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
  2. In the Connections pane, go to the site, application, or directory for which you want to set a custom HTTP header.
  3. In the Home pane, double-click HTTP Response Headers.

  4. In the HTTP Response Headers pane, click Add... in the Actions pane.

  5. In the Add Custom HTTP Response Header dialog box, set the name and value for your custom header, and then click OK.

Configuration

Attributes

None.

Child Elements

Element Description
add Optional element.

Adds a custom response header to the <customHeaders> collection.
clear Optional element.

Removes all references to custom response headers from the <customHeaders> collection.
remove Optional element.

Removes a reference to a custom response header from the <customHeaders> collection.

Configuration Sample

The following configuration sample sets a custom HTTP header and value.

<configuration>
   <system.webServer>
      <httpProtocol>
         <customHeaders>
            <add name="X-Custom-Name" value="MyCustomValue" />
         </customHeaders>
      </httpProtocol>
   </system.webServer>
</configuration>

Note: The following default <httpProtocol> element is configured in the ApplicationHost.config file in IIS 7.

<httpProtocol>
   <customHeaders>
      <clear />
      <add name="X-Powered-By" value="ASP.NET" />
   </customHeaders>
   <redirectHeaders>
      <clear />
   </redirectHeaders>
</httpProtocol>

Sample Code

The following code samples set a custom HTTP header and value.

AppCmd.exe

appcmd.exe set config "Default Web Site" -section:system.webServer/httpProtocol /+"customHeaders.[name='X-Custom-Name',value='MyCustomValue']" 

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetWebConfiguration("Default Web Site");
         ConfigurationSection httpProtocolSection = config.GetSection("system.webServer/httpProtocol");
         ConfigurationElementCollection customHeadersCollection = httpProtocolSection.GetCollection("customHeaders");

         ConfigurationElement addElement = customHeadersCollection.CreateElement("add");
         addElement["name"] = @"X-Custom-Name";
         addElement["value"] = @"MyCustomValue";
         customHeadersCollection.Add(addElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample

   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Default Web Site")
      Dim httpProtocolSection As ConfigurationSection = config.GetSection("system.webServer/httpProtocol")
      Dim customHeadersCollection As ConfigurationElementCollection = httpProtocolSection.GetCollection("customHeaders")

      Dim addElement As ConfigurationElement = customHeadersCollection.CreateElement("add")
      addElement("name") = "X-Custom-Name"
      addElement("value") = "MyCustomValue"
      customHeadersCollection.Add(addElement)

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site";
var httpProtocolSection = adminManager.GetAdminSection("system.webServer/httpProtocol", "MACHINE/WEBROOT/APPHOST/Default Web Site");
var customHeadersCollection = httpProtocolSection.ChildElements.Item("customHeaders").Collection;

var addElement = customHeadersCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "X-Custom-Name";
addElement.Properties.Item("value").Value = "MyCustomValue";
customHeadersCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site"
Set httpProtocolSection = adminManager.GetAdminSection("system.webServer/httpProtocol", "MACHINE/WEBROOT/APPHOST/Default Web Site")
Set customHeadersCollection = httpProtocolSection.ChildElements.Item("customHeaders").Collection

Set addElement = customHeadersCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "X-Custom-Name"
addElement.Properties.Item("value").Value = "MyCustomValue"
customHeadersCollection.AddElement(addElement)

adminManager.CommitChanges()
Deprecated Elements