UDDI .NET SDK

The UDDI .NET SDK is a collection of components, sample code and reference documentation enabling the .NET programmer to interact with the range of UDDI compliant servers.

In this documentation you will find:

  • UDDI .NET SDK overview – providing an introduction to the facilities offered by this SDK

  • UDDI.NET SDK samples – demonstrating how to use this SDK to achieve the typical operations that a programmer will perform against UDDI servers

  • Advanced topics – explaining more advanced material, such as the initial discovery of the available UDDI servers within an organization and representing WSDL described web services

  • Advanced samples – demonstrating the code required for more advanced UDDI interactions

  • Reference – detailing the objects, methods, properties and enumerations exposed by the SDK components


Platforms supported

The UDDI .NET SDK is supported on the following platforms:

  • Microsoft® Windows® XP Professional with the .NET Framework

  • Microsoft® Windows® 2000 Professional with Service Pack 2.0 and the .NET Framework

  • Microsoft® Windows® 2000 Server with Service Pack 2.0 and the .NET Framework

  • Microsoft® Windows® 2000 Advanced Server with Service Pack 2.0 and the .NET Framework

  • Microsoft® Windows® .NET Server


Copyright and legal information

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, email addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, places or events 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.

© 2000 - 2001 Microsoft Corporation. All rights reserved.

Access 2000, Active Accessibility, Active Directory, ActiveX, Authenticode, BizTalk, ClearType, CodeView, DataTips, DirectDraw, DirectMusic, DirectX, Exchange Server, FrontPage, IntelliMirror, IntelliMouse Explorer, IntelliSense, Internet Explorer, Microsoft, Microsoft Press, Money, MSDN Library, MS-DOS, MSN, MSN Hotmail, Natural, OpenType, Outlook, PowerPoint, SQL Server, Systems Management Server, Visual Basic, Visual Basic .NET, Visual Basic Scripting Edition (VBScript), Visual C# .NET, Visual C++ .NET, Visual FoxPro, Visual InterDev, Visual Studio, Visual Studio .NET, WebTV, Where do you want to go today?, Win32, Win32s, Windows, Windows 95, Windows 98, Windows 2000, Windows Millennium Edition, Windows .NET server family, Windows NT, and Windows XP 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.


UDDI .NET SDK Overview

The UDDI .NET SDK consists of:

  • A client side .NET assembly (a series of components) that enables the .NET programmer to interact at a high level with UDDI servers. The programmer is abstracted away from manual construction of the UDDI API XML messages.

  • A collection of documentation that explains the use of this assembly and details how it can be used in typical scenarios.

  • A series of sample applications that demonstrate simple and more advanced use of the assembly.

Note This SDK assumes that you are familiar with the UDDI Programmer’s API Specification (versions 1 and 2), the UDDI Data Structures Reference (versions 1 and 2) and the SOAP 1.1 Technical Recommendation and XML.


Features supported

The UDDI .NET SDK includes support for the following:

  • Support for UDDI Version 1.0 Programmer's API Specification

  • Support for UDDI Version 1.0 Data Structure Reference

  • Support for UDDI Version 2.0 Programmer's API Specification

  • Support for UDDI Version 2.0 Data Structure Specification

  • Support for W3C Simple Object Access Protocol (SOAP) 1.1, W3C Note 08 May 2000 specification

  • Support for features offered in Microsoft Windows .NET UDDI Services such as Windows Authentication


A quick introduction to UDDI

High level description of the purpose and goals of UDDI.

Note: this will be intentionally brief and is not designed to be the first place that a reader will go to find out about UDDI. This page will finish with pointers to relevant articles and sites.

To be taken from the introduction in the “UDDI SDK Programmer’s Guide” from the VS6 SDK and / or from the “UDDI Programmer’s API 1.0” document on www.uddi.org.


Details specific to Windows .NET UDDI Services

Following on from the UDDI introduction piece this is a high level discussion around the differences between speaking to a public node and a private Windows .NET UDDI Services node.

Topics covered will include the differences in the authentication mechanism and the Active Directory bootstrap for finding servers.


UDDI .NET SDK Samples

The UDDI .NET SDK includes a series of samples that demonstrate the code required to achieve the following tasks:

  • Finding information at a UDDI node

  • Getting details from a UDDI node

  • Registering information in a UDDI node

  • Error handling

  • Internationalization


Finding information at a UDDI node

The initial step in accessing the information held in UDDI server involves finding the entries of interest. To illustrate this, this page presents the approach for:

  • Finding a business

  • Finding a tModel

  • Finding a service

  • Finding a binding

  • Interpreting the results

Finding a Business

Create a new project using the Console Application template

Add Reference to Microsoft.Uddi.Sdk assembly

Add the namespace references:

using Microsoft.Uddi;
using Microsoft.Uddi.Api;

Add the following lines to the Main function:

// Configure the site that we are going to access
Inquire inq = new Inquire();
Inquire.Url = "http://uddi.microsoft.com/inquire";

// Create an object to find a business
FindBusiness fb = new FindBusiness();
fb.Name = "Microsoft";

// Send the prepared find business request
BusinessList bizList = fb.Send();
Console.WriteLine("Businesses found=" + bizList.BusinessInfos.Count.ToString());

Compile this code and execute this console application from the command prompt. This will return the businesses that match the given search term – “Microsoft” in this case. Note that a leftmost search is performed so this find will return all businesses that begin with “Microsoft” such as “Microsoft Corporation.”

This same search can be performed against a machine running Windows .NET UDDI Services simply be changing the inquiry URL to http://intranetUDDI/inquire/inquire.asmx.

Using wildcards in searches

If the full name of the business is not known then wildcard character % may be used. For example, setting the Name parameter of the FindBusiness object to “%soft%” would return all businesses that have “soft” in their name. Furthermore, since a leftmost search is being performed, setting the Name parameter of the FindBusiness object to “%soft” would perform an identical search.

Using qualifiers in searches

It is possible to be more specific over the query that is executed. The following code will add two elements from the find qualifiers enumeration set (FindQualiferEnum) to produce a more specific query. Replace the code in the Main function with the following:

// Configure the site that we are going to access
Inquire inq = new Inquire();
Inquire.Url = "http://uddi.microsoft.com/inquire";

// Create an object to find a business
FindBusiness fb = new FindBusiness();
fb.Name = "Microsoft";

// Set parameters to control the query that is executed
fb.FindQualifiers.Add(FindQualifierEnum.sortByNameAsc);
fb.FindQualifiers.Add(FindQualifierEnum.caseSensitiveMatch);
fb.MaxRows = 100;

// Send the prepared find business request
BusinessList bizList = fb.Send();

Interpreting the results

After having executed the previous code, the BusinessList object should contain the results of the query execution. These results include a BusinessInfos collection including the top level details about the matching businesses, identification details about the Operator that executed the query, and a Boolean property specifying whether the details were complete or Truncated.

Add the following lines to the end of the Main function:

// How many businesses were found
Console.WriteLine(bizList.BusinessInfos.Count.ToString() + " matching businesses found at " + bizList.Operator.ToString());

// Were the results truncated by the server?
if (bizList.Truncated == Microsoft.Uddi.Api.TruncatedEnum.True)
    Console.WriteLine("The results were truncated");

// If we have any businesses
if (bizList.BusinessInfos.Count >0)
{
    // Output the business name
    Console.WriteLine("Provider name:" + bizList.BusinessInfos[0].Name);

    // Output any business descriptions – there may be a description in more than one language
    for (int i=0; i<bizList.BusinessInfos[0].Descriptions.Count; i++)
        Console.WriteLine(bizList.BusinessInfos[0].Descriptions[i].Text);

    // Output any services and their identifying keys
    for (int j=0; j<bizList.BusinessInfos[0].ServiceInfos.Count; j++)
    {
        Console.WriteLine("Service: " + bizList.BusinessInfos[0].ServiceInfos[j].Name);
        Console.WriteLine("  Business key = " + bizList.BusinessInfos[0].ServiceInfos[j].BusinessKey);
        Console.WriteLine("  Service key = " + bizList.BusinessInfos[0].ServiceInfos[j].ServiceKey);
    }
}

The BusinessKey and ServiceKey values provide a link to the fully detailed information about the registered businesses and services and these keys should be used when “Getting details from a UDDI node.”

Finding a tModel

Create a new project using the Console Application template

Add Reference to Microsoft.Uddi.Sdk assembly

Add the namespace references:

using Microsoft.Uddi;
using Microsoft.Uddi.Api;

Add the following lines to the Main function:

// Configure the site that we are going to access
Inquire inq = new Inquire();
Inquire.Url = "http://uddi.microsoft.com/inquire";

// Create an object to find a tModel
FindTModel ft = new FindTModel();
ft.Name = "uddi-org:inquiry";

TModelList tList = ft.Send();

// How many businesses were found
Console.WriteLine(tList.TModelInfos.Count.ToString() + " matching tModels found at " + tList.Operator.ToString());

// Were the results truncated by the server
if (tList.Truncated == Microsoft.Uddi.Api.TruncatedEnum.True)
    Console.WriteLine("The results were truncated");

// If we have any businesses
if (tList.TModelInfos.Count >0)
{
    // Output the tModel name
    Console.WriteLine("tModel name:" + tList.TModelInfos[0].Name);
Console.WriteLine("tModel key:" + tList.TModelInfos[0].TModelKey);
}

Note that the tModel descriptions and further details are not immediately available but the TModelKey value provide a link to the fully detailed information about the registered tModel and this key should be used when “Getting details from a UDDI node” with a call to XXXX


Getting details from a UDDI node

After having decided upon a business from the previous example and having found the relevant key information it is then possible to get the full details from a UDDI server. This page will present the approach for using:

  • get_businessDetail

  • get_businessDetailExt

  • get_serviceDetail

  • get_tModelDetail

  • get_bindingDetail


Registering information in a UDDI node

Present code fragments that show how to:

  • Authenticate against UDDI Services or a public registry (present the options and relate them to the server settings)

  • Register a tModel (not using WSDL – that is covered in an advanced sample)

  • Register a business with minimal information

  • Register more complex business information exercising business identifiers and contacts, services with taxonomy details and bindings to a tModel.

  • Get_authtoken

  • Get_registeredInfo

  • Save_binding

  • Save_business

  • Save_service

  • Save_tModel

  • Discard_authToken

At the end of this piece, the code fragments will be presented together as a full commented listing that can be copied into a VS.Net project.

Presented in C# and VB.Net.


Deleting information in a UDDI node

Demonstrate how to delete the details previously published:

  • delete_business

  • delete_binding

  • delete_service

  • delete_tModel

Explain the effects of deletion – explain when items are items hidden or removed.

At the end of this piece, the code fragments will be presented together as a full commented listing that can be copied into a VS.Net project.

Presented in C# and VB.Net


Error handling

[Discussion of the error reporting system including code fragment to demonstrate error interpretation.]

Error Codes

[taken from spec – to be edited]

The following list of error codes can be returned in the errno values within a dispositionReport response to the API calls defined in this programmer’s reference. The descriptions in this section are general and when used with the specific return information defined in the individual API call descriptions are useful for determining the reason for failures.

  • E_authTokenExpired: (10110) signifies that the authentication token information has timed out.

  • E_authTokenRequired: (10120) signifies that an invalid authentication token was passed to an API call that requires authentication.

  • E_accountLimitExceeded: (10160) signifies that a save request exceeded the quantity limits for a given structure type. See "Structure Limits" in Appendix D for details.

  • E_busy: (10400) signifies that the request cannot be processed at the current time.

  • E_categorizationNotAllowed: (20100) Restrictions have been placed by the on the types of information that can categorized within a specific taxonomy. The data provided does not conform to the restrictions placed on the category used. Used with cateborization only.

  • E_fatalError: (10500) signifies that a serious technical error has occurred while processing the request.

  • E_invalidKeyPassed: (10210) signifies that the uuid_key value passed did not match with any known key values. The details on the invalid key will be included in the dispositionReport structure.

  • E_invalidCategory (20000): signifies that the given keyValue did not correspond to a category within the taxonomy identified by the tModelKey. Used with categorization only.

  • E_invalidURLPassed: (10220) signifies that an error occurred during processing of a save function involving accessing data from a remote URL. The details of the HTTP Get report will be included in the dispositionReport structure.

  • E_keyRetired: (10310) signifies that a uuid_key value passed has been removed from the registry. While the key was once valid as an accessor, and is still possibly valid, the publisher has removed the information referenced by the uuid_key passed.

  • E_languageError: (10060) signifies that an error was detected while processing elements that were annotated with xml:lang qualifiers. Presently, only the description element supports xml:lang qualifiacations.

  • E_nameTooLong: (10020) signifies that the partial name value passed exceeds the maximum name length designated by the policy of an implementation or Operator Site.

  • E_operatorMismatch: (10130) signifies that an attempt was made to use the publishing API to change data that is mastered at another Operator Site. This error is only relevant to the public Operator Sites and does not apply to other UDDI compatible registries.

  • E_success: (0) Signifies no failure occurred. This return code is used with the dispositionReport for reporting results from requests with no natural response document.

  • E_tooManyOptions: (10030) signifies that incompatible arguments were passed.

  • E_unrecognizedVersion: (10040) signifies that the value of the generic attribute passed is unsupported by the Operator Instance being queried.

  • E_unknownUser: (10150) signifies that the user ID and password pair passed in a get_authToken message is not known to the Operator Site or is not valid.

  • E_unsupported: (10050) signifies that the implementor does not support a feature or API.

  • E_userMismatch: (10140) signifies that an attempt was made to use the publishing API to change data that is controlled by another party. In certain cases, E_operatorMismatch takes precedence in reporting an error.


Internationalization

[Discussion and demonstration of publishing multi-language registrations.]

Taken from Programmer’s API spec…

Use of multiple languages in the description elements.

Many of the messages defined in this programmers interface specification contain an element named description. Multiple descriptions are allowed to accommodate multiple language descriptions. These description elements are also permitted to be sent without an xml:lang attribute qualifier.

Only one description element is allowed to be passed to a save_xx API call without an xml:lang attribute qualifier. Elements passed in this way will be assigned the default language code of the registering party. This default language code is established at the time that publishing credentials are established with an individual Operator Site.

If more than one description element is sent in a document being stored, only the first description element in a particular structure may be sent without a xml:lang attribute qualifier. All subsequent description peers must contain an xml:lang qualifier.

Valid Language Codes

The valid values for language codes are to be specified as ISO language codes. Values for these codes and translation to other common language code sets can be found at:

http://www.unicode.org/unicode/onlinedat/languages.html

Only one description element is allowed for each language code used at any given container level.

Default Language Codes

A default ISO language code will be determined for a publisher at the time that a party establishes permissions to publish at a given Operator Site or implementation. This default language code will be applied to any description values that are provided with no language code.

On data returned via the SOAP interface, all descriptions will contain xml:lang qualifications.


Advanced topics

The UDDI SDK includes a series of more advanced topics, with the required code, that demonstrate approaches for the following tasks:

  • Initial discovery of Windows .NET UDDI Services – Microsoft Active Directory can be used to assist in finding Windows .NET UDDI Services nodes within an organization.

  • Registering WSDL described services – the Web Service Description Language provides a machine interpretable XML based format for precisely describing web service interfaces. This page provides a consistent “best practice” approach for registering these descriptions in a UDDI directory.


Initial discovery of Windows .NET UDDI Services

[How to interact with an Active Directory service to discover where UDDI nodes are on your network.

Not documented - requires feature to be designed.]


Registering WSDL described services

[How to register services for which you have a WSDL description.

Based on http://www.uddi.org/pubs/wsdlbestpractices-V1.05-Open-20010625.doc

Possible diagram based on slide 20 in the deck:

http://uddiweb/docs/SHADOW/Documents/Marketing/SRV241_Januszewski(2.0).ppt

Mention registering for discovery from within VisualStudio.Net developer environment. Should document if VS.NET cannot find services in a Heartland server.

Based on http://uddiweb/Main/Documents/Code%20Samples/How%20to%20register%20your%20webservice.doc

How to register your web services in UDDI and also make them discoverable from within the VBA add in. Point out that only simple type services are currently compatible.]


Advanced samples

The UDDI .NET SDK includes a series of more advanced samples that demonstrate the code required to achieve the following tasks:

  • UDDI Explorer – a richer sample that demonstrates the progressive drill down through the UDDI data structures to provide progressively more detail. This illustrates extensive use of the get and find APIs along with interpreting of the results for display.

  • Duplicate service selection – a sample that demonstrates the run time use of UDDI to elegantly deal with web service failure scenarios.


UDDI explorer

[Describe the purpose, approach and the files that make up the application.

Describe that this sample is demonstrating the drilldown query model.

This sample would be a relatively minor modification of the UDDI Publish from the SDK Beta. Alterations include:

  • Add the option of initial UDDI node selection through Active Directory integration

  • Bug fixing

The sample is presented only in C#.]


Duplicate service selection

[Describe the purpose, approach and the files that make up the application.

This sample is intended to demonstrate the runtime use of UDDI for selecting a duplicate instance of a service in the failover situation.

The code will demonstrate an exception handler that will use calls to UDDI to deal with a potential HTTP 404 exception.

Initial thoughts:

A script (or instructions) will create two identical HelloWorld (or similarly simple) web services on localhost and register them in UDDI (demonstrating the relationship between WSDL and tModels). A simple client app will query UDDI to discover an instance of the service and will repeatedly call the service (on a 10 second timer). The running instance of the service will then be killed and the client app will handle the exception and query UDDI again to find a replacement service which it will then proceed to use. This will obviously require less than trivial configuration but it is designed as an advanced sample and demonstrates a concept that is important to grasp.

A simple alternative to this would include only the client pieces but this would not be able to run “out of the box”

This would be a new sample presented only in C#.]


Guidelines and limitations

What parts of what specs do we not have great coverage of today

  • No support for UDDI Version 2.0 Operator's Specification


Reference

[To be linked in]