XmlUrlResolver Class

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Resolves external XML resources named by a Uniform Resource Identifier (URI).

Namespace:   System.Xml
Assembly:  System.Xml (in System.Xml.dll)


public class XmlUrlResolver : XmlResolver
public ref class XmlUrlResolver : XmlResolver
type XmlUrlResolver = 
        inherit XmlResolver
Public Class XmlUrlResolver
	Inherits XmlResolver
System_CAPS_pubmethod XmlUrlResolver

Initializes a new instance of the XmlUrlResolver class.


Gets or sets the cache policy for the underlying WebRequest object.


Sets credentials used to authenticate web requests.(Overrides .)


Gets or sets the network proxy for the underlying WebRequest object.

System_CAPS_pubmethod Equals

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethod Finalize

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethod GetEntity

Maps a URI to an object that contains the actual resource.(Overrides XmlResolverGetEntity.)

System_CAPS_pubmethod GetEntityAsync

Asynchronously maps a URI to an object that contains the actual resource.(Overrides XmlResolverGetEntityAsync.)

System_CAPS_pubmethod GetHashCode

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethod GetType

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_protmethod MemberwiseClone

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethod ResolveUri

Resolves the absolute URI from the base and relative URIs.(Overrides XmlResolverResolveUri.)

System_CAPS_pubmethod SupportsType

Enables the resolver to return types other than System.IOStream.(Inherited from XmlResolver.)

System_CAPS_pubmethod ToString

Returns a string that represents the current object.(Inherited from Object.)

XmlUrlResolver is used to resolve external XML resources such as entities, document type definitions (DTDs) or schemas. It is also used to process include and import elements found in Extensible StyleSheet Language (XSL) style sheets or XML Schema definition language (XSD) schemas.

XmlUrlResolver is the default resolver for all classes in the System.Xml namespace. It supports the file:// and http:// protocols and requests from the WebRequest class.

System_CAPS_security Security Note

XmlUrlResolver objects can contain sensitive information such as user credentials. You should be careful when you cache XmlUrlResolver objects and should not pass XmlUrlResolver objects to an untrusted component.

If an XML reader ( XmlReader) is reading an XML file that contains an external DTD, it calls the XmlUrlResolverGetEntityAsync method to get a stream representation of the DTD. If the URI of the DTD is a relative URI, the XML reader calls the XmlUrlResolverResolveUri method and returns an absolute URI for the given relativeUri and baseURi parameters. If the XmlUrlResolver doesn't know how to resolve the URI, it returns null.

The XmlUrlResolverGetEntity method uses the information in the property as appropriate to gain access to the resource. There is no get accessor to this property for security reasons. When overwriting XmlResolver, GetEntity is the method that utilizes the credential information in the Credentials property.

Resolving all other XML resources is very similar to resolving DTDs. XmlResolver negotiates the connection with the external resource and returns a Stream representation of the content. The object that is making the call to XmlResolver interprets the stream.

The default behavior of the XmlUrlResolver class is to resolve an XML data resource from its source, not from cache. In some cases, resolving a data resource from cache can improve the performance of an application by saving a trip to the data resource's server. The performance gains here must be weighed against the need for up-to-date content.

The following example extends XmlUrlResolver and builds a new class, XmlCachingResolver, to retrieve resources from the cache. This is done by overriding the property and the XmlUrlResolverGetEntity method.

class XmlCachingResolver : XmlUrlResolver
    bool enableHttpCaching;
    ICredentials credentials;

    //resolve resources from cache (if possible) when enableHttpCaching is set to true
    //resolve resources from source when enableHttpcaching is set to false 
    public XmlCachingResolver(bool enableHttpCaching)
        this.enableHttpCaching = enableHttpCaching;

    public override ICredentials Credentials
            credentials = value;
            base.Credentials = value;

    public override object GetEntity(Uri absoluteUri, string role, Type ofObjectToReturn)
        if (absoluteUri == null)
            throw new ArgumentNullException("absoluteUri");
        //resolve resources from cache (if possible)
        if (absoluteUri.Scheme == "http" && enableHttpCaching && (ofObjectToReturn == null || ofObjectToReturn == typeof(Stream)))
            WebRequest webReq = WebRequest.Create(absoluteUri);
            webReq.CachePolicy = new HttpRequestCachePolicy(HttpRequestCacheLevel.Default);
            if (credentials != null)
                webReq.Credentials = credentials;
            WebResponse resp = webReq.GetResponse();
            return resp.GetResponseStream();
        //otherwise use the default behavior of the XmlUrlResolver class (resolve resources from source)
            return base.GetEntity(absoluteUri, role, ofObjectToReturn);
Class XmlCachingResolver
    Inherits XmlUrlResolver
    Dim enableHttpCaching As Boolean
    Public Shadows Credentials As ICredentials

    'resolve resources from cache (if possible) when enableHttpCaching is set to true
    'resolve resources from source when enableHttpcaching is set to false
    Public Sub New(ByVal enableHttpCaching As Boolean)
        Me.enableHttpCaching = enableHttpCaching
    End Sub

    Public Shadows Function GetEntity(ByVal absoluteUri As Uri, ByVal role As String, ByVal returnType As Type) As Object
        If absoluteUri = Nothing Then
            Throw New ArgumentNullException("absoluteUri")
        End If

        'resolve resources from cache (if possible)
        If absoluteUri.Scheme = "http" And enableHttpCaching And (returnType Is GetType(Nullable) Or returnType Is GetType(Stream)) Then
            Dim webReq As WebRequest = WebRequest.Create(absoluteUri)
            webReq.CachePolicy = New HttpRequestCachePolicy(HttpRequestCacheLevel.Default)
            If Not (Credentials Is Nothing) Then
                webReq.Credentials = Credentials
            End If
            Dim resp As WebResponse = webReq.GetResponse()
            Return resp.GetResponseStream()
            'otherwise use the default behavior of the XmlUrlResolver class (resolve resources from source)
            Return MyBase.GetEntity(absoluteUri, role, returnType)
        End If

    End Function
End Class

The caching behavior of the XmlCachingResolver class is implemented in the GetEntity method. This is done by creating new WebRequest and HttpRequestCachePolicy objects. The HttpRequestCachePolicy object is created using the Default member of the HttpRequestCacheLevel enumeration.

The property of the WebRequest object is set with the HttpRequestCachePolicy object.

An instance of the XmlCachingResolver class is created with the BooleanenableHttpCaching. When this value is set to true, the instance resolves a resource from the default cache if possible. When enableHttpCaching is set to false, the instance uses the default behavior and resolves resources from their source.


This example leverages the extensibility of the XML classes in the .NET Framework. Other classes can be extended and customized to suit the needs of a particular application.

The following example creates an XmlReader that uses an XmlUrlResolver with default credentials.

// Create an XmlUrlResolver with default credentials.
XmlUrlResolver resolver = new XmlUrlResolver();
resolver.Credentials = CredentialCache.DefaultCredentials;

// Create the reader.
XmlReaderSettings settings = new XmlReaderSettings();
settings.XmlResolver = resolver;
XmlReader reader = 
     XmlReader.Create("http://serverName/data/books.xml", settings);
' Create an XmlUrlResolver with default credentials.
Dim resolver As New XmlUrlResolver()
resolver.Credentials = CredentialCache.DefaultCredentials

' Create the reader.
Dim settings As New XmlReaderSettings()
settings.XmlResolver = resolver
Dim reader As XmlReader = _
   XmlReader.Create("http://serverName/data/books.xml", settings)
.NET Framework
Available since 1.1

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top