HttpPlatformHandler 配置参考

项目
07/19/2023

由 IIS 团队

本文概述了 HttpPlatformHandler 并说明了模块的配置。

功能概述

HttpPlatformHandler 是 IIS 模块，适用于 IIS 8+，它执行以下两项操作：

http 侦听器的进程管理 - 这可以是可在端口上侦听 http 请求的任何进程。例如 - Tomcat、Jetty、Node.exe、Ruby 等;
向它管理的进程发出代理请求。

HttpPlatformHandler 配置

HttpPlatformHandler 通过站点或应用程序web.config文件进行配置，并在 system.webServer 中有自己的配置节 - httpPlatform。

配置属性

Attribute	说明
`processPath`	必需的特性。将启动侦听 HTTP 请求的进程的可执行文件或脚本的路径。从 v1.2 开始支持相对路径，如果路径以“.”开头，则认为路径相对于网站根目录。没有默认值
`arguments`	可选的字符串值。 processPath设置中指定的可执行文件或脚本的参数。没有默认值。
`startupTimeLimit`	可选的整数属性。 HttpPlatformHandler 等待可执行文件/脚本开始侦听端口的进程的持续时间（以秒为单位）。如果超出此时间限制，HttpPlatformHandler 将终止进程，然后尝试重新启动 startupRetryCount 次。默认值为 `10`。
`startupRetryCount`	可选的整数属性。 HttpPlatformHandler 尝试启动 processPath 中指定的进程的次数。有关详细信息，请参阅 startupTimeLimit。默认值为 `10`。
`rapidFailsPerMinute`	可选的整数属性。指定允许 processPath 中指定的进程每分钟崩溃的次数。如果超出此限制，则 HttpPlatformHandler 会在每分钟达到此限制后的剩余时间内停止启动该进程。 managedPipelineMode 属性可以是以下可能的值之一。默认为 `10`。
`requestTimeout`	可选的 timespan 属性。指定 HttpPlatformHandler 等待侦听 `%HTTP_PLATFORM_PORT%`的进程响应的持续时间。默认值为“00：02：00”。
`stdoutLogEnabled`	可选的布尔属性。如果为 true，则 processPath 设置中指定的进程的 stdout 和 stderr 将重定向到 stdoutLogFile 中指定的文件。默认值`false`为。
`stdoutLogFile`	可选的字符串属性。指定将记录 processPath 中指定的进程中的 stdout 和 stderr 的相对 OR 绝对文件路径。相对路径与站点根目录相对。从 v1.2 开始，任何以“.”开头的路径都将相对于网站根目录，所有其他路径将被视为绝对路径。默认值为 `httpplatform-stdout.`
`processesPerApplication`	可选的整数属性。指定 processPath 设置中指定的进程实例数，这些实例可按应用程序启动。最大值为 100。默认值为 `1`。
`forwardWindowsAuthToken`	True 或 False。 v1.2 的新增功能。如果此设置设置为 true，则令牌将作为每个请求的标头“X-IIS-WindowsAuthToken”转发到侦听 %HTTP_PLATFORM_PORT% 的子进程。进程负责为每个请求调用此令牌上的 CloseHandle。默认值为 `false`。

子元素

元素	说明
environmentVariables	为 processPath 设置中指定的进程配置 environmentVariables 集合。
recycleOnFileChange	配置文件集合，当对指定列表中的文件进行更改时，该文件集合将回收工作进程。元素语法，例如 <file path=“.\touch.txt”/> 或 <file path=“c:\file.txt”/>

HttpPlatformHandler 配置示例

下面是运行具有不同进程的多个应用程序的配置示例。

Tomcat

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat" 
                  arguments="" 
                  stdoutLogEnabled="true" 
                  stdoutLogFile="\\?c:\dev\javasites\log.txt">
      <environmentVariables>
        <environmentVariable name="JRE_HOME" value="%programfiles%\java\jdk1.8.0_25" />
        <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value"/>
        <environmentVariable name="CATALINA_HOME" value="c:\dev\javasites\bin\apache-tomcat-8.0.15" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

Jetty

<?xml version="1.0"?>
<configuration>
    <system.webServer>
      <handlers>
        <add name="httpplatformhandler" path="*" verb="*" modules ="httpPlatformHandler" resourceType="Unspecified"/>
      </handlers>
      <httpPlatform processPath="c:\Program Files\Java\jdk1.8.0_25\bin\java.exe" 
                    arguments="-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP_PLATFORM_PORT% -Djetty.base=&quot;c:\dev\javasites\bin\jetty-distribution-9.2.6.v20141205&quot; -jar &quot;c:\dev\javasites\bin\jetty-distribution-9.2.6.v20141205\start.jar&quot;" 
                    startupTimeLimit="20" 
                    startupRetryCount="20" 
                    stdoutLogEnabled="true"></httpPlatform>
    </system.webServer>
</configuration>

代码示例

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("JavaSites");
            
            ConfigurationSection httpPlatformSection = config.GetSection("system.webServer/httpPlatform");
            httpPlatformSection["processPath"] = @"c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat";
            httpPlatformSection["arguments"] = @"";
            httpPlatformSection["stdoutLogFile"] = @"=""\\?c:\dev\javasites\log.txt";
            
            ConfigurationElementCollection environmentVariablesCollection = httpPlatformSection.GetCollection("environmentVariables");
            
            ConfigurationElement environmentVariableElement = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement["name"] = @"JRE_HOME";
            environmentVariableElement["value"] = @"=""%programfiles%\java\jdk1.8.0_25";
            environmentVariablesCollection.Add(environmentVariableElement);
            
            ConfigurationElement environmentVariableElement1 = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement1["name"] = @"CATALINA_OPTS";
            environmentVariableElement1["value"] = @"=""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value";
            environmentVariablesCollection.Add(environmentVariableElement1);
            
            ConfigurationElement environmentVariableElement2 = environmentVariablesCollection.CreateElement("environmentVariable");
            environmentVariableElement2["name"] = @"CATALINA_HOME";
            environmentVariableElement2["value"] = @"c:\dev\javasites\bin\apache-tomcat-8.0.15";
            environmentVariablesCollection.Add(environmentVariableElement2);
            
            serverManager.CommitChanges();
        }
    }
}

Javascript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/JavaSites";

var httpPlatformSection = adminManager.GetAdminSection("system.webServer/httpPlatform", "MACHINE/WEBROOT/APPHOST/JavaSites");
httpPlatformSection.Properties.Item("processPath").Value = "c:\\dev\\javasites\\bin\\apache-tomcat-8.0.15\\bin\\startup.bat";
httpPlatformSection.Properties.Item("arguments").Value = "";
httpPlatformSection.Properties.Item("stdoutLogFile").Value = "=\"\\\\?c:\\dev\\javasites\\log.txt";

var environmentVariablesCollection = httpPlatformSection.ChildElements.Item("environmentVariables").Collection;

var environmentVariableElement = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement.Properties.Item("name").Value = "JRE_HOME";
environmentVariableElement.Properties.Item("value").Value = "=\"%programfiles%\\java\\jdk1.8.0_25";
environmentVariablesCollection.AddElement(environmentVariableElement);

var environmentVariableElement1 = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement1.Properties.Item("name").Value = "CATALINA_OPTS";
environmentVariableElement1.Properties.Item("value").Value = "=\"-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value";
environmentVariablesCollection.AddElement(environmentVariableElement1);

var environmentVariableElement2 = environmentVariablesCollection.CreateNewElement("environmentVariable");
environmentVariableElement2.Properties.Item("name").Value = "CATALINA_HOME";
environmentVariableElement2.Properties.Item("value").Value = "c:\\dev\\javasites\\bin\\apache-tomcat-8.0.15";
environmentVariablesCollection.AddElement(environmentVariableElement2);

adminManager.CommitChanges();

命令行 (AppCmd)

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /processPath:"c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat" /arguments:"" /stdoutLogFile:"="""\\?c:\dev\javasites\log.txt"  

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='JRE_HOME',value='="""%programfiles%\java\jdk1.8.0_25']" 

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='CATALINA_OPTS',value='="""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value']" 

appcmd.exe set config "JavaSites" -section:system.webServer/httpPlatform /+"environmentVariables.[name='CATALINA_HOME',value='c:\dev\javasites\bin\apache-tomcat-8.0.15']"

PowerShell

Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "processPath" -value "c:\dev\javasites\bin\apache-tomcat-8.0.15\bin\startup.bat"
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "arguments" -value ""
Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform" -name "stdoutLogFile" -value "="""\\?c:\dev\javasites\log.txt"

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='JRE_HOME';value='="""%programfiles%\java\jdk1.8.0_25'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='CATALINA_OPTS';value='="""-Dport.http=%HTTP_PLATFORM_PORT% -Dsomeotherconfig=value'}

Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/JavaSites'  -filter "system.webServer/httpPlatform/environmentVariables" -name "." -value @{name='CATALINA_HOME';value='c:\dev\javasites\bin\apache-tomcat-8.0.15'}

HttpPlatformHandler 配置参考

功能概述

HttpPlatformHandler 配置

配置属性

子元素

HttpPlatformHandler 配置示例

Tomcat

Jetty

代码示例

C#

Javascript

命令行 (AppCmd)

PowerShell

反馈

反馈

其他资源