Adding Listener Adapters <add>

Article
05/14/2020

Overview

The <add> element of the <listenerAdapters> specifies configuration settings for a non-HTTP listener adapter that can be used by Windows Process Activation Service (WAS) to communicate with a listener service.

Compatibility

Version	Notes
IIS 10.0	The `<add>` element was not modified in IIS 10.0.
IIS 8.5	The `<add>` element was not modified in IIS 8.5.
IIS 8.0	The `<add>` element was not modified in IIS 8.0.
IIS 7.5	The `<add>` element was not modified in IIS 7.5.
IIS 7.0	The `<add>` element of the `<listenerAdapters>` element was introduced in IIS 7.0.
IIS 6.0	N/A

Setup

The <add> element of the <listenerAdapters> element is included in the default installation of IIS 7.

How To

There is no user interface for adding listener adapters for IIS 7. For examples of how to add listener adapters programmatically, see the Code Samples section of this document.

Configuration

Attributes

Attribute	Description
`identity`	Optional string attribute. Specifies a local account name, a domain account, or a built-in account. The identity is used to help secure the WAS communication channel between the listener service and the listener adapter.
`name`	Required string attribute. Specifies the unique name of the listener adapter to which WAS connects the listener service.
`protocolManagerDll`	Optional string attribute. Specifies the fully qualified path or short name of the DLL that contains the listener adapter's code. The DLL must be found on disk (by using standard search procedures that depend on DLL type) in order for the function specified in protocolManagerDllInitFunction to be called.
`protocolManagerDllInitFunction`	Optional string attribute. Specifies the name of the function to call in the custom listener adapter code. The DLL specified in the protocolManagerDll attribute must contain the function specified in the protocolManagerDllInitFunction attribute. Note: This attribute is case-sensitive; you must use the correct case when you specify the name of the initialization function.

Child Elements

None.

Configuration Sample

The following configuration sample adds a listener adapter for a Gopher protocol provider, and specifies both the name of the DLL and its initialization function.

<system.applicationHost>
   <listenerAdapters>
      <add name="gopher"
         protocolManagerDll="%SystemRoot%\system32\inetsrv\gophersvc.dll"
         protocolManagerDllInitFunction="GopherInit" />
   </listenerAdapters>
</system.applicationHost>

Sample Code

The following code samples add a listener adapter for a Gopher protocol provider, and specify both the name of the DLL and its initialization function.

AppCmd.exe

appcmd.exe set config -section:system.applicationHost/listenerAdapters /+"[name='gopher',protocolManagerDll='%SystemRoot%\system32\inetsrv\gophersvc.dll',protocolManagerDllInitFunction='GopherInit']" /commit:apphost

Note

You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

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.GetApplicationHostConfiguration();
         ConfigurationSection listenerAdaptersSection = config.GetSection("system.applicationHost/listenerAdapters");
         ConfigurationElementCollection listenerAdaptersCollection = listenerAdaptersSection.GetCollection();

         ConfigurationElement addElement = listenerAdaptersCollection.CreateElement("add");
         addElement["name"] = @"gopher";
         addElement["protocolManagerDll"] = @"%SystemRoot%\system32\inetsrv\gophersvc.dll";
         addElement["protocolManagerDllInitFunction"] = @"GopherInit";
         listenerAdaptersCollection.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.GetApplicationHostConfiguration
      Dim listenerAdaptersSection As ConfigurationSection = config.GetSection("system.applicationHost/listenerAdapters")
      Dim listenerAdaptersCollection As ConfigurationElementCollection = listenerAdaptersSection.GetCollection

      Dim addElement As ConfigurationElement = listenerAdaptersCollection.CreateElement("add")
      addElement("name") = "gopher"
      addElement("protocolManagerDll") = "%SystemRoot%\system32\inetsrv\gophersvc.dll"
      addElement("protocolManagerDllInitFunction") = "GopherInit"
      listenerAdaptersCollection.Add(addElement)

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var listenerAdaptersSection = adminManager.GetAdminSection("system.applicationHost/listenerAdapters", "MACHINE/WEBROOT/APPHOST");
var listenerAdaptersCollection = listenerAdaptersSection.Collection;

var addElement = listenerAdaptersCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "gopher";
addElement.Properties.Item("protocolManagerDll").Value = "%SystemRoot%\\system32\\inetsrv\\gophersvc.dll";
addElement.Properties.Item("protocolManagerDllInitFunction").Value = "GopherInit";
listenerAdaptersCollection.AddElement(addElement);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set listenerAdaptersSection = adminManager.GetAdminSection("system.applicationHost/listenerAdapters", "MACHINE/WEBROOT/APPHOST")
Set listenerAdaptersCollection = listenerAdaptersSection.Collection

Set addElement = listenerAdaptersCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "gopher"
addElement.Properties.Item("protocolManagerDll").Value = "%SystemRoot%\system32\inetsrv\gophersvc.dll"
addElement.Properties.Item("protocolManagerDllInitFunction").Value = "GopherInit"
listenerAdaptersCollection.AddElement(addElement)

adminManager.CommitChanges()

Share via