Troubleshooting BizTalk Web Services

This section offers advice on how to identify and resolve common Web service issues.

You can enable tracing to debug the BizTalk Web Services Publishing Wizard by uncommenting the <add> node in the BTSWebSvcWiz.exe.config file. For more information about obtaining trace information from the Web Services Publishing Wizard, see How to Modify BTSWebSvcWiz.exe.config.

You can enable SOAP message tracing to help you debug the Web services publishing application by using a SOAP extension. For more information about SOAP extensions, see How to: Implement a SOAP Extension.

If an error occurs, the Web client receives a generic SoapException.

To debug your published Web service, you can add a switch to the web.config file to control the level of the exception details returned from the published Web service. The switch is ThrowDetailedError, and when it is set to True the server proxy returns inner exception information to the Web client, enabling you to debug the published Web service.

The following XML code shows the ThrowDetailedError switch that appears in the web.config file under the <appSettings> node:

<appSettings>
  <add key="ThrowDetailedError" value="False" />
<appSettings/>

The .NET Framework System.Diagnostics.Trace class can be used to capture and write errors to a text file.

1. Update the web.config file for the Web service to set the TRACE compiler directive to true and add a TraceSwitch value:

   <?xml version="1.0"?>
   <configuration>
     <system.codedom>
       <compilers>
         <compiler language="c#;cs;csharp"
                   extension=".cs"
                   compilerOptions="/d:TRACE"
                   type="Microsoft.CSharp.CSharpCodeProvider, System, Version=2.0.3500.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" warningLevel="1" />
         </compilers>
     </system.codedom>
     <system.diagnostics>
       <switches>
         <add name="WebSvcTraceSwitch" value="2" />
         <!-- Set to 0, 1, 2, 3, or 4, which corresponds
         to TraceLevel.Off, TraceLevel.Error, TraceLevel.Warning
         TraceLevel.Info, and TraceLevel.Verbose. -->
       </switches>
     </system.diagnostics>
   </configuration>
   

   Note

   If the TRACE compiler directive is not set to true then no trace output will be generated. The TraceSwitch value can also be set in the calling class but is set here in the web.config file for convenience. Set the TraceSwitch value to the appropriate level for development purposes and change the value after development is complete to reduce or inhibit trace output.

2. Create an instance of the TraceSwitch and TextWriterTraceListener classes and use a try…catch block in the Web service [WebMethod] call to trap and write errors to a trace output file. For example, the following code traps an error that is generated when attempting to set the integer variable s2 to a null instance of the object variable o2:

   using System;
   using System.Web;
   using System.Web.Services;
   using System.Web.Services.Protocols;
   using System.Diagnostics;
   
   [WebService(Namespace = "http://tempuri.org/")]
   [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
   public class Service : System.Web.Services.WebService
   {
       TraceSwitch WebSvcTraceSwitch = new TraceSwitch("WebSvcTraceSwitch", "Web Service Trace");
       TextWriterTraceListener TestTracer = new TextWriterTraceListener("C:\\traceout.txt");
   // Note that by default the local ASPNET account(IIS 5.x) or the
   // local NETWORK SERVICE account(IIS 6.0) needs write access to
   // this directory so that the instance of the
   // TextWriterTraceListener can write to the trace output file.
   );
   
       public Service () {
       }
   
       [WebMethod]
       public string HelloWorld()
       {
       string h2 = "Hello World";
       //object o2 = 1;
       object o2 = null;
           try
           {
               int s2 = (int)o2; //Error if o2 set to null
               return h2;
           }
           catch(Exception e)
           {
               Trace.Listeners.Add(TestTracer);
               Trace.WriteLineIf(WebSvcTraceSwitch.Level = TraceLevel.Warning,"Exception caught: " + e.Message);
               //Writes to the trace file if specified TraceLevel switch value (in web.config) >= 2
               TestTracer.Dispose();
               return "An error occurred in the Web service, please contact the web server administrator.";
           }
       }
   }
   

   Note

   This code is a modified version of the HelloWorld Web service that is generated by default when you create a new ASP.Net Web Service project in Visual Studio.

   Note

   For Windows Vista, Administrator privileges may be required to write the trace output file to the root folder.

3. Rebuild the Web service project. Now, if an error occurs in the Try statement the exception is handled in the Catch statement and an error is written to the trace output file.

This section contains a set of questions and answers designed to help you resolve issues with Web services.

There are many details to consider when consuming a Web service, including the following:

• Avoid using two underscore characters in a parameter name.

• Use of the any element or the anyAttribute attribute is not supported in Web methods.

• Avoid using XLANG/s keywords as a Web service name or Web method name.

• Avoid using Web method parameter types that are not supported by XLANG/s.

• Do not use element names that are C# keywords or will be invalid as a C# identifier in your schemas.

• Avoid Web Services Description Language (WSDL) files with multiple service or port type definitions.

• Web method parameters must be Xml Serializable.

• Avoid references to consumed Web services that contain multi-rooted schemas.

• Avoid referencing Web services with Web methods expecting generic-based parameters such as nullable parameters.

• The WSDL import element is not supported.

  For more information about these and related considerations, see Considerations When Consuming Web Services.

Schemas cannot be published if they include circular references (the included schema has an include element to the including schema) or have an unresolved schemaLocation attribute.

For more information about the limitation of the include element, see Include Element Binding Support. The Web Services Publishing Wizard has the same limitations as XSD.exe in .NET Framework 2.0; for more information, see Import Element Binding Support.

If you have an envelope schema that you are publishing as a Web service, you need to manually modify the generated Web project.

1. Open the <myWebService>.asmx.cs file.

2. Edit the file and change bodyTypeAssemblyQualifiedName = <dll.name.version> to bodyTypeAssemblyQualifiedName = null

If Web clients that use .NET Framework are calling a Web service generated with the BizTalk Server Web Services Publishing Wizard, it is possible that the client cannot receive server script time-out errors because the client request time-out occurs first by default. To resolve this problem you can do one of the following:

• Increase the client request time-out to a value greater than the server script time-out by increasing the value for the HttpWebRequest.Timeout property on the client.

• Reduce the server script time-out to a value less than the client request time-out by reducing the value for the HttpServerUtility.ScriptTimeout property on the server.

Attempts to call a Web service return an HTTP 404 (File Not Found) error.

This error can occur if ASP.NET is not installed and/or enabled on the IIS server that hosts the Web service.

Ensure that ASP.NET is installed and enabled. Install the .NET Framework if it is not installed and/or run the aspnet_regiis.exe program located in the %WinDir%\Microsoft.NET\Framework\vXXX.XXX\ folder of the IIS server.

When you process a document with a web service that was generated with the BizTalk Server Web Services Publishing Wizard, any data contained in a field with a Data Type of xs:date is removed from the document.

This problem can occur if the published orchestration contains a schema with one or more fields that have a Data Type of xs:date and a Nillable property of True.

To workaround this problem, locate the fields in the published schema that have a Data Type of xs:date and verify that the Nillable property of these fields is set to False.

When you call a Web service in a Microsoft ASP.NET Web application, you may receive the following error:

System.IO.FileNotFoundException

This error can occur if either of the following conditions is true:

• The worker process does not have permissions to read to the process Temp directory, and the worker process does not have permissions to write to the process Temp directory.

• There are compilation errors in the code that XmlSerializer generated.

This error is documented in Microsoft Knowledge Base article 823196. Follow the steps in the Resolution section of this Knowledge Base article to resolve this error.