Windows 7 and Windows Server 2008 R2 introduce the new framework for building web services in C++ code. Windows Web Services API (WWSAPI) supports the core set of protocols for SOAP-based web services. Developers can use WWSAPI in applications where they need to use native C/C++ code and they cannot take dependency on .Net Framework. Solutions built with this API require significantly less memory than WCF on the client side. On the server side, the API allows developers to achieve much higher throughput than WCF. You can find links to all online resources available to you to learn more about this new API on this page. WWS API is available on all versions of Windows 7 and Windows Server 2008 R2 and it can also be deployed to Windows XP, Vista, Server 2003 and Server 2008.  The redistributable installers are available on a formal request to wwsredst@microsoft.com with a brief description of plans for using this runtime and the business contact information for your company.

The Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1 plays a very important role in this story of enabling developers to connect their native C and C++ code to web services. Here is what Windows SDK delivers for this scenario:

1) webservices.h header is part of the set of headers installed. This header contains declarations of all functions and types that are part of the API. If Windows SDK did not contain this header, you would get the following error when trying to build code that uses WWSAPI:

> fatal error C1083: Cannot open include file: 'WebServices.h': No such file or directory

If you see this error when you try to use WWSAPI or build samples from MSDN, you need to:

a) Install Windows SDK for Windows 7.

b) Run the Windows SDK Configuration Tool to utilize the Windows 7 headers and libraries.  Go to Start > All Programs > Microsoft Windows SDK v7.0 > Visual Studio Registration > Windows SDK Configuration Tool.

c) After these two steps, you should be able to compile the code that uses WWSAPI. To complete linking of your application, you will need webservices.lib.

2) webservices.lib library contains declarations of exports from the Windows Web Services Runtime DLL (webservices.dll). There are three versions of this library installed by Windows SDK for each of CPU architecture (x86, x64 and Itanium). After you completed steps 1.a. and 1.b. from above, you may still get LNK2001 errors for Ws*() functions used in your code. Here is an example of such errors:

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsCreateError@12

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsFreeError@4

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsCloseServiceProxy@12

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsFreeHeap@4

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsCreateHeap@24

1>SortServiceClient.obj : error LNK2001: unresolved external symbol _WsOpenServiceProxy@16

1>sortservice.wsdl.obj : error LNK2001: unresolved external symbol _WsCreateServiceProxyFromTemplate@40

1>sortservice.wsdl.obj : error LNK2001: unresolved external symbol _WsCreateServiceEndpointFromTemplate@56

1>sortservice.wsdl.obj : error LNK2001: unresolved external symbol _WsCall@32

1>C:\C++ Project that uses WWSAPI.exe : fatal error LNK1120: 12 unresolved externals

To resolve these errors, you need to point VC++ linker to use webservices.lib to build the final binary. You can do this by opening properties of your project. Then browse to Linker options and add webservices.lib to the list of Additional Libraries. See picture below for details:

Once you do that, all linker errors should go away.

3)

clip_image002


Wsutil.exe is Windows Web Services Tool for generating C code from metadata that describes a web service. You are most likely to use this tool as the first step when you need to implement a client to an existing web services or create a new web service. This tool serves the same purpose as WCF Service Model Metadata Utility Tool (Svcutil.exe). There are many commands available in this tool, which you can read about by passing “/?” or “/help” option on the command line. However the core steps for using this tool are:

a. Save your metadata files somewhere on the local hard drive.

i. If you need to download metadata from a running web service, you can use svcutil.exe as follows:

> svcutil.exe /t:metadata <URL to Web Service>

b. Run wsutil.exe on the SDK Shell prompt either as

> wsutil.exe *.wsdl *.xsd

    or

> wsutil.exe /wsdl:<filename> /xsd:<filename> /wsp:<filename>           

When you run wsutil.exe, it is going to process each WSDL, XML schema and policy file and generates one C header and one C source file for each input file.

Please note that you need to provide all WSDL and XSD files at once. Passing an incomplete set will result in wsutil.exe issuing errors for references in the input files to non-present WSDL or XSD files. Make sure that you pass all WSDL and XSD files in one call to the wsutil.exe.

For more information please refer to the Windows Web Services API documentation on MSDN.

4) Wstrace.bat and wstracedump.exe are tools that help you with enabling and collecting Windows Web Services Tracing. With these tools you can:

1. Create and delete a trace log

2. Enable and disable tracing

3. Update the tracing level

4. Converting trace logs to CSV files

You can find a tutorial on how to use these tools with Windows 7 RC in this post on Nikola’s blog. For more information please refer to the WWSAPI documentation on MSDN.

5) 92 samples for WWSAPI. Each sample is a complete application that demonstrates how to use WWSAPI in a particular scenario end-to-end. Most of Service Model and Channel Layer samples come in pairs. One sample demonstrates the client side and another one demonstrates the server side. There is usually one example for showing how to use some functions from XML Layer. Assuming that you have not changed the default install path for Windows SDK, you can find all samples under this folder C:\Program Files\Microsoft SDKs\Windows\v7.0\Samples\Web\WWSAPI.

To build WWSAPI samples

1. Copy sample from C:\Program Files\Microsoft SDKs\Windows\v7.0\Samples\Web\WWSAPI to a some other folder with all other projects of yours

2. Open a sample in Visual Studio

3. Select Build Solution from the Build Menu.

4. Run the Windows SDK Configuration Tool to utilize the Windows 7 headers and libraries.  Go to Start > All Programs > Microsoft Windows SDK v7.0 > Visual Studio Registration > Windows SDK Configuration Tool.

a. If you see any build errors, please make sure you have completed integrating Windows SDK with Visuals Studio.

b. If you still experience errors, please post your issue on the forum.

To run samples that demonstrate a scenario from both client and server sides, you should:

1. Run the sample for the server side of a scenario first. For example, run HttpCalculatorService first before running HttpCalculatorClient.

2. Run the sample that demonstrates the client side after the server side has started.

If the sample is not part of client-server pair, just run the sample after the build is completed.

For more information please refer to the Using Windows Web Services documentation on MSDN.

6) The Windows SDK also installs a local version of the MSDN documentation for WWSAPI. Once you install Windows SDK and integrate it with Visual Studio, pressing F1 should allow you to get documentation installed with Windows SDK. Please note however, that the online documentation tends to be more accurate because technical writers update online version more frequently.

As you can see, the Windows SDK plays a very important role in this scenario. To learn more about WWSAPI and how you can use it in your C++ code, please see these other resources:

1) Video recordings

a. Introduction to WWSAPI and a tutorial on building native C/C++ clients to web services using WWSAPI at PDC 2008.

b. Advantages for using native C/C++ code in building web services and key steps that developers have to take can be found in the session at TechEd 2009.

c. An open discussion about Windows Web Services API with answers to frequently asked questions can be found in a recording on Channel 9.

2) Follow links to all online resources available for building web services and clients to web services in C and C++ code on this page.

3) Follow Web Services in Native C++ code series of posts on Nikola’s blog and Hao’s blog.

If you have any questions or if you would like to participate in discussions about WWSAPI, please visit the forum or just comment on this post.

 

Send your thoughts to the Windows SDK Feedback alias.  Tell us how you use the SDK and what we can do to improve your development experience.

The MSDN Windows SDK Developer Center is the place to find resources and links to Windows SDK products, release notes, technical articles, and more.