Metadata Import

  • Article

The WWSAPI includes API elements that can be used to process WSDL and Policy from an endpoint with the goal of extracting information that can be used to communicate with the endpoint. These APIs are typically used when the communication protocol supported by the endpoint is not already known.

Use the following sequence to process metadata:

WsCreateMetadata    // create a metadata object

while there are metadata documents to add
{
    // retrieve the metadata document from it's location
    // (download, read from file, etc)

    // add the document to the metadata object
    WsReadMetadata

    // optionally query the metadata object for any missing documents
    WsGetMissingMetadataDocumentAddress?
}

// get the endpoints from the metadata object
WsGetMetadataEndpoints

for each endpoint
{            
    // examine the endpoint information to see if 
    // the endpoint is relevant for the particular scenario

    if the endpoint is relevant
    {
        // get the policy object from the endpoint

        // get the number of policy alternatives in the policy
        WsGetPolicyAlternativeCount

        for each policy alternative
        {
            // construct a policy constraints structure that specifies
            // what policy is acceptable and what information to extract
            // from the policy

            // see if the policy alternative matches the constraints
            WsMatchPolicyAlternative

            // if there is a match, then use it

            // if there is not a match, then it is also possible to 
            // try with a different constraint structure
        }
    }
}

// If reusing the metadata object for a different set of documents
WsResetMetadata? // reset metadata object, which removes all documents

WsFreeMetadata // free the metadata object

for information about how WSDL and WS-Policy assertions correspond to the API, see the Metadata Mapping topic.

Security

The metadata downloaded is only as good as the address used to download it. An application should ensure that is trusts the address. Also, an application should ensure that it uses a security protocol to download the metadata documents that does not allow tampering with the metadata.

An application should inspect the addresses of the services exposed by the metadata. By default, the runtime ensures that the host name of the service matches that of the original URL used to download the metadata, but the application may want to perform additional checks. An application can disable the host name verification by overwriting WS_METADATA_PROPERTY_VERIFY_HOST_NAMES property. If the hostname check that is done by default is disabled, the application will need to protect itself against the metadata documents containing the address of a service from a different party that it does not trust in some other way.

By default, the maximum amount of memory used by the metadata runtime to deserialize and process the metadata is 256k, and the maximum number of documents that may be added is 32. These default values can be overwritten by WS_METADATA_PROPERTY_HEAP_REQUESTED_SIZE and WS_METADATA_PROPERTY_MAX_DOCUMENTS properties. These bounds are designed to limit the amount of downloads and limit the amount of memory allocated in order to accumulate the metadata. Increasing these values may lead to excessive memory usage, CPU usage, or network bandwidth consumption. Note that due to expansion of dictionary strings in the binary format, a small message may lead to a much larger deserialized form, so relying on small messages to limit metadata memory allocation is not sufficient when using the binary format.

By default, the maximum number of policy alternatives is 32, though it can be overwritten by WS_POLICY_PROPERTY_MAX_ALTERNATIVES property. If an application loops through each alternative looking for a match, it may need to search all alternatives before finding a match. Increasing the maximum number of alternatives may lead to excessive CPU utilization.

The following enumerations are part of metadata import:

The following functions are part of metadata import:

The following handles are part of metadata import:

The following structures are part of metadata import: