微软Azure网站是一个多租户托管环境。Azure网站为每个站点自动生成一个applicationhost.config配置文件。该applicationhost.config包含已经优化的默认设置,适用于大多数的网站。在某些特定的情况下,您可能要更改根据您的应用要求的默认设置。但是,您并有没有办法直接编辑配置文件。通过强大的XML文档转换功能,您可以修改任何配置。

在本文中,我们将讨论如何使用XDT变换更改Web站点配置。

我把该文章以英文版发布在全球技术支持团队的博客。
http://blogs.msdn.com/b/waws/archive/2014/06/17/transform-your-microsoft-azure-web-site.aspx

XML文档转换

XML文档转换功能为ASP.NET 4的一个功能。ASP.NET 4转换引擎需要一个XML源文件(例如,web.config文件)和一个转换XML文件(如web.prod.config),产生并输出一个XML文件(生产环境的web.config)。该XDT引擎库可以从Nuget上下载。

转换XML文件的根元素必须指定XML-Document-Transform命名空间。 XML-Document-Transform命名空间定义两个属性来指定转换操作:定位器(Locator)和转换(Transform)。

定位器属性告诉转型引擎如何找到要更改/转换元素(或多个元素)。所支持的方式是:

  • 与某个节点的属性值相匹配
  • 精确的XPath匹配
  • 条件匹配

transform属性告诉转换引擎需要对找的的元素进行什么样的转换。支持的操作包括:

  • 更换节点
  • 插入一个节点
  • 删除一个节点
  • 删除属性
  • 设置属性

有关XML文档转换的详细信息,请阅读该MSDN文档

转换Azure网站的站点配置

Azure的网站允许通过XML文档转换(XML Document Transformation)的方式更改站点的applicationHost.config。要使用此功能,您需要:

1. 创建转换文件,并将它命名为applicationHost.xdt,然后上传该文件到网站根目录。

/site
    applicationhost.xdt
    /wwwroot

2. 重新启动该网站
您可以通过Azure管理门户重新启动该网站,或通过SCM站点

Azure网站定义了一组传递给转换引擎的环境变量可以协助寻找元素,或设置适当的属性。

  • XDT_SITENAME是当前站点名称
  • XDT_SCMSITENAME是当前SCM站点名称
  • XDT_EXTENSIONPATH是特定版本的扩展的物理路径
  • HOME是网站的根路径

配置转换实例

配置失败请求跟踪(FREB)响应缓慢的页面
失败请求跟踪功能记录失败的请求,包括处理请求中涉及到的IIS组件已经每个组件所耗费的时间等详细的信息。如果你正试图提高站点性能或排查一个特定的 HTTP 错误,失败请求跟踪功能非常有用。

有关如何在Azure网站中使用此功能,请参考该文档

运行在Azure网站上的站点启用此功能后,如果HTTP响应状态代码在400~600之间,将生成一个跟踪文件。有时,您需要使用FREB排查响应很慢,但成功的跟踪请求(HTTP响应状态代码为200)。我写了另外一篇文章,谈到了如何启用FREB跟踪缓慢的请求。在那篇文章中介绍的方法需要手动修改您的web.config。现在,我们可以通过配置转换来实现相同的功能。
1.创建applicationhost.xdt并上传至/site文件夹,applicationhost.xdt包含如下内容。
<?xml version=”1.0″?>
    <configuration xmlns:xdt=”http://schemas.microsoft.com/XML-Document-Transform”>
        <system.applicationHost>
            <sites>
                <site name=”%XDT_SITENAME%” xdt:Locator=”Match(name)”>
                    <traceFailedRequestsLogging enabled=”true”  customActionsEnabled=”true”
                        directory=”D:\home\LogFiles” xdt:Transform=”SetAttributes(enabled)”/>
                </site>
            </sites>
        </system.applicationHost>

        <system.webServer>
            <tracing>
                <traceFailedRequests>
                    <add path=”*”>
                            <failureDefinitions statusCodes=”400-600″ timeTaken=”00:00:10″
                                xdt:Locator=”Match(statusCodes)” xdt:Transform=”SetAttributes(timeTaken)”/>
                    </add>
                </traceFailedRequests>
            </tracing>
        </system.webServer>
    </configuration>
2. 重启网站
通过该转换文件,我们修改了FREB跟踪的条件。现在,只要满足下面两个条件之一就会产生跟踪文件:

  • 请求在IIS管道花费的时间超过10秒
  • 或者,HTTP响应状态码为400〜〜600

插入环境变量
我们有客户使用bson模块的时候,遇到下面的错误。
insert env
这是因为bson项目是基于VS2005版本的,而在Azure网站上并没有VS2005的编译环境。我们通过下面的配置转换文件添加了一个环境变量告诉Node.js使用VS2012的编译环境来编译bson项目。

<?xml version=”1.0″?>

<configuration xmlns:xdt=”http://schemas.microsoft.com/XML-Document-Transform”>

    <system.webServer>

        <runtime xdt:Transform=”Insert“>

           <environmentVariables>

              <add name=” GYP_MSVS_VERSION ” value=”2012“/>

           </environmentVariables>

        </runtime>

    </system.webServer>

</configuration>

在kudu项目网站上,您可以找到更多的例子

使用CTT工具测试转换文件
XDT配置转换功能强大,但是并不容易掌握。很多时候需要尝试很多次才能获得期望的结果。如果直接基于Azure网站进行测试,耗时耗力,而且容易导致生产环境出现问题。
CTT工具是基于XDT转换引擎的命令行工具,可以用来测试转换结果。CTT工具可以从CodePlex下载。您可以遵循下面的步骤利用CTT工具在本地测试转换结果。
1. 利用Kudu控制台下载applicationhost.config到本地。
2. 创建转换文件applicationhost.xdt。
3. 运行CTT工具,具体命令行参数如下:
ctt s:”applicationHost.config” t:”applicationhost.xdt” d:”result.xml” v
您可以查看result.xml检查转换结果。另外,”v”选项打印详细输出信息。下图是一个CTT命令行的具体输出结果。

CTT
配置转换日志
Azure网站在进行配置转换的时候会生成日志。如果在转换过程中遇到问题,日志中会包含有用的信息。下面是一个转换日志中的实际例子。

2014-05-27T06:14:38 :(15,12), Microsoft.Web.XmlTransform.XmlNodeException: No attribute ‘name’ exists for the Match Locator —> Microsoft.Web.XmlTransform.XmlTransformationException: No attribute ‘name’ exists for the Match Locator

   at Microsoft.Web.XmlTransform.Match.ConstructPredicate()

   at Microsoft.Web.XmlTransform.Locator.ConstructPath()

   at Microsoft.Web.XmlTransform.Locator.ConstructPath(String parentPath, XmlElementContext context, String argumentString)

   at Microsoft.Web.XmlTransform.XmlElementContext.ConstructXPath()

 

配置转换日志在/Logfiles/Transform目录下。
transform log
注意事项
1. 配置转换在站点启动之前,因此在更新转换文件后需要重启站点。
2. 如果在配置转换中发生错误,会导致您的网站无法访问。
3. 如果转换后的结果是错误的,同样会导致网站无法访问。

参考文档
XML Document Transformation
kudu Xdt transform samples
CTT
New Azure Web Sites feature: configurable environment variables

Leave a comment

电子邮件地址不会被公开。 必填项已用*标注