Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
© 2002 Microsoft Corporation. All rights reserved.
Microsoft, MS-DOS, Windows, Windows NT, BizTalk, Visio, Visual Basic, and Visual C++ are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
The following software components should be installed to leverage all of the features available in BizTalk Adapter for Web Services. Optional components are noted as not required.
To remove BizTalk Adapter for Web Services from your computer, run the Uninstall
application located in the Control Panel, Add/Remove Applications.
This installation does not support a direct upgrade from the Beta Version. Follow the steps below to maintain the original configuration created with any previous version of BizTalk Adapter for Web Services.
The following items are known issues.
If you enter an invalid Single Sign-on server name or database name, a SingleSignon exception occurs: "SingleSignonException caught. Fail to change the credentials." The new configuration settings did not take effect. The settings will remain the same as they were before you entered the server name and database name. See your SharePoint Portal Server system administrator for the correct server name and database name for Single Sign-on.
The second option for data transformation on the Request and Response Parameters dialog works as follows: if you select an optional child node from an optional parent node, the parent node does not appear in the instance XML document. Additionally, the parent node will not appear in the method signature in the proxy class that is created when consuming the Web service. If the value of the parent node is required, you need to include a separate node under the parent with the value of the parent, and include this node when you specify the input schema.
The BizTalk Server Schema Editor is used to define the XDR schema. The root node in the XDR schema may have one of the following values for the Order attribute:
If the Order attribute is set to equal '1', then only one child element defined in an ElementType can appear. When a Web client generates a call to BizTalk Adapter for Web Services, it will populate every child, which may not be a valid instance for the XDR schema.
For example, to specify that an Item element can contain either a Product element or a BackOrderedProduct, but not both elements, the XDR schema can be specified in the following manner to avoid an error. Wrap the XDR schema with another root node.
If the original schema looks like this:
<root1 order=’1’>
<child1 />
<child2 />
<child3 />
<child4 />
</root1>
Wrap it like this:
<root2>
<root1 order=’1’>
<child1 />
<child2 />
<child3 />
<child4 />
</root1>
</root2>
The same XDR schema cannot be used within the same Web service as two separate Web methods, since using the same name for two Web methods causes an error. To avoid this potential error, use this approach: create two different Web services and create one Web method for each Web service using the identical XDR schema.
To solve this problem, BizTalk Adapter for Web Services converts the XDR data types to .NET strings, instead of the corresponding .NET data types. The following table shows the valid data type conversions.
XDR XSD Valid Values
boolean string "1" or "0"
char string string of length 1
fixed.14.4 float floats that fall under the format specification
uuid string uuid formatted string with no "{}" characters
date string YYYY-MM-DD
time string HH:MM:SS
dateTime string YYYY-MM-DDTHH:MM:SS
You do not need to make any changes to the XDR. The Web Services Description Language (WSDL) will show strings instead of the above data types. You need to ensure that the string data are in the correct format.
Optionally, you may replace the following data types in the XDR to ensure data validation for these data types:
date - replace with dateTime.tz
time - replace with dateTime.tz
dateTime - replace with time.tz (replaces both date and time)
When you select option 3, Use Prebuilt Schemas, you need to ensure the Request Web Method schema and the Response Web Method schema each contain the TargetnameSpace in the following format:
<web service namsespace>/<methodName>[In | Out]
The Web service namespace refers to the Web service you created in the Create a Web Service Wizard. The methodName is the name of the Web method you created in the Create a Web Method Wizard. "In" specifies this as the Request schema. "Out" specifies this as the Response schema. For example, if the Web service name is Sample.com, and the methodName is M1, the Request schema needs to declare targetnameSpace = "Sample.com/M1In", and the Response schema needs to declare targetnameSpace = "Sample.com/M1Out."
When using Option 3, Use Prebuilt Schemas, you cannot reuse any schemas. However, you can copy the schema and change the targetnameSpace values for each Web method.
When you create a Web service, BizTalk Adapter for Web Services requires you to place the Web service in the virtual root of the virtual directory you created in Internet Information Services (IIS). The Web service cannot be added to a Web directory under the virtual root.
When the wizard creates Web methods, several temporary files are created in the %temp% folder. The location of this folder is set to C:\Documents and Settings\<userID>\Local Settings\Temp by default. When left this way, the files are protected and periodically cleaned-up by the system. To access the files, someone would need the privileges of the userID in the above path . However, the system administrator can change the default location of the %temp% folder to c:\temp. In this case, these files are no longer protected and are not automatically cleaned-up. In this case, it is important that the user immediately delete all files from this directory upon completing the wizard.
The wizards create a *.asmx and a web.config file in the selected virtual directory. It is up to the user to secure the virtual directory so that unwanted users do not get access to these files.
Anonymous access is not recommended. Authenticated access should be set to the maximum security settings possible, given the implementation requirements. The physical directory should also be protected against unauthorized access. Only administrators should have write, modify, and full control permissions to these directories.
The user needs to ensure that all files in the Custom Assemblies folder are sufficiently protected against unauthorized access. The Custom Assemblies folder is located in the root of the installation directory.
It is recommended that the user follow these steps to improve performance between BizTalk Adapter for Web Services and BizTalk Server.
Note: BizTalk Adapter for Web Services tends to be more effective in scaling out across servers rather than scaling up with more processors.
BizTalk Adapter for Web Services can be installed on a server computer that does not contain BizTalk Server 2002. You must install the following software on the server computer on which you install this adapter:
Internet Information Services (IIS) must be installed and configured according to BizTalk Server 2002 requirements. Additionally, the BizTalk Server Interchange Application DCOM application must be exported from the production BizTalk Server computer to the production server computer on which the BizTalk Adapter for Web Services is installed.
In order to create new Web services, you must use a server computer that contains both BizTalk Server 2002 and BizTalk Adapter for Web Services. This configuration could serve as a development environment. Administration and deployment using the Web Services Administration Console on a non-BizTalk Server 2002 computer are not supported.
To deploy a Web service from the development environment to the production environment, follow these steps:
1. Create the Web service on the development BizTalk Server computer.
2. Create a virtual directory on the production server computer where the adapter resides.
3. From the development server computer, copy web.config from <install_path>\bin to the virtual directory of the production server computer.
4. From the development server computer, copy the generated file <webservicename>.asmx from the virtual directory to the virtual directory of the production server computer.
5. From the development server computer, copy the generated file <webservicename>.xml from the installation directory\configuration to <install_path>\configuration on the production server computer, where the adapter resides.
The ASPNET worker process gets recycled automatically once allocated system memory exceeds sixty percent. If you experience high-volume processing where SOAP documents have a large size, BizTalk Adapter for Web Services may allocate main memory that exceeds this sixty percent limit. Consequently, you may encounter one of the following messages:
To prevent these error messages, try one or all of the following approaches:
3.16 Double-byte characters
To support double-byte characters with BizTalk Adapter for Web Services, follow the steps below to change the request and response schemas:
BizTalk Adapter for Web Services can use a custom processor to retrieve and/or modify:
To use a custom processor with BizTalk Adapter for Web Services
using System;
using System.IO;
using System.Collections;
using System.Collections.Specialized;
using Microsoft.BizTalk2002.WebService.Runtime;
namespace SampleCustomProcess
{
/// <summary>
/// Summary description for Class1.
/// </summary>
public class CSampleCustomProcess : IPreProcess,IPostProcess
{
public CSampleCustomProcess()
{
//
// TODO: Add constructor logic here
//
}
public string PreProcess(string PayLoad,IDictionary HeadersDict)
{
// The SOAP Headers, HTTP Headers, and Server Variables are passed
// in via the IDictionary object. The code below demonstrates one
// method of accessing this data.
ArrayList SoapHdrs=(ArrayList) HeadersDict[PreProcessKeys.SoapHeaders];
NameValueCollection HttpHdrs = (NameValueCollection)HeadersDict[PreProcessKeys.HttpHeaders];
NameValueCollection ServerVars = (NameValueCollection)HeadersDict[PreProcessKeys.ServerVariables];
// A valid payload must be returned, it gets passed to BizTalk
return PayLoad;
}
public string PostProcess(string PayLoad,IDictionary HeadersDict)
{
// The SOAP Headers, HTTP Headers, and Server Variables are passed
// in via the IDictionary object. The code below demonstrates one
// method of accessing this data.
ArrayList SoapHdrs=(ArrayList) HeadersDict[PostProcessKeys.SoapHeaders];
IDictionary HttpHdrs = (IDictionary)HeadersDict[PostProcessKeys.HttpHeaders];
IDictionary HttpCookies = (IDictionary) HeadersDict[PostProcessKeys.HttpCookies];
// This code demonstrates adding new SOAP and HTTP Headers and HTTP Cookies
SoapHdrs.Add("<soap:Header>Test</soap:Header>");
HttpHdrs.Add("CustomHttpKey1","CustomHttpValue1");
HttpCookies.Add("CustomCookieKey1","CustomHttpValue1");
// A valid payload must be returned, it gets validated against
// the response schema and sent to the SOAP client.
return PayLoad;
}
}
}