Getting Started

This topic covers how to get started using the XML language from the Web Languages Add-on, implemented by the XmlSyntaxLanguage class, and lists its requirements for supporting advanced features like parsing and automated IntelliPrompt.

It is very important to follow the steps in this topic to configure the language correctly so that its advanced features operate as expected.

Configure the Ambient Parse Request Dispatcher

The language's parser does a lot of processing when text changes occur. To ensure that these parsing operations are offloaded into a worker thread that won't affect the UI performance, you must set up a parse request dispatcher for your application.

The ambient parse request dispatcher should be set up in your application startup code as described in the Parse Requests and Dispatchers topic.

protected override void OnStartup(StartupEventArgs e) {
	...
	AmbientParseRequestDispatcherProvider.Dispatcher = new ThreadedParseRequestDispatcher();
	...
}

Likewise it should be shut down on application exit, also as described in the Parse Requests and Dispatchers topic.

protected override void OnExit(ExitEventArgs e) {
	...
	var dispatcher = AmbientParseRequestDispatcherProvider.Dispatcher;
	if (dispatcher != null) {
		AmbientParseRequestDispatcherProvider.Dispatcher = null;
		dispatcher.Dispose();
	}
	...
}

Configure the XmlSchemaResolver

Next, create a XmlSchemaResolver instance and use the methods described in the Schema Resolver topic to initialize it with one or more XSD files. If you use DTDs for validation instead, you can ignore this step.

The XmlSchemaResolver is used to provide data consumed for supporting automated IntelliPrompt and validation, so it is essential that you configure it with a schema data that describes the XML that will be edited.

XSD files can be found on the Internet for common XML formats, and custom XSDs can be created for any other XML format. The Internet has a lot of great information on how to create XSD files. Please do Internet searches if you need assistance building your own XSD files.

This code creates a XmlSchemaResolver and loads an XSD file that is located on the hard drive at the path specified by the path variable:

XmlSchemaResolver resolver = new XmlSchemaResolver();
resolver.LoadSchemaFromFile(path);

Configure DTD Support

We recommend that if you have the option, you use XML schemas (XSD files) instead of DTDs to provide validation for your XML. XML schemas also enable automated IntelliPrompt features like completion lists that aren't available when using DTDs.

If you do wish to support DTDs for validation, you must set an option on the XmlValidator language service and then register it on the language. It is not enabled by default since DTDs can sometimes attempt to access external resources.

This code creates a XmlValidator that allows DTD validation support:

XmlValidator validator = new XmlValidator();
validator.Mode = XmlValidatorMode.Dtd;

Configure the XmlSyntaxLanguage

The next step is to create an instance of the XmlSyntaxLanguage class and register the XmlSchemaResolver as a "feature" service on it so that other language services can consume the schema data. If DTD validation support is desired, you can also register the XmlValidator as a "feature" service.

This code creates a XmlSyntaxLanguage and registers the XmlSchemaResolver service:

XmlSyntaxLanguage language = new XmlSyntaxLanguage();
language.RegisterXmlSchemaResolver(resolver);  // If XML schema support is desired
language.RegisterXmlValidator(validator);  // If DTD validation support is desired

Use the XmlSyntaxLanguage

The final step is to use the language on the ICodeDocument instances that will be editing XML.

This code applies the language to a document in a SyntaxEditor, whose instance is in the editor variable:

editor.Document.Language = language;

Assembly Requirements

The following list indicates the assemblies that are used with the XML syntax language implementation in this add-on.