Getting Started

This topic covers how to get started using the Visual Basic language from the .NET Languages Add-on, implemented by the VBSyntaxLanguage 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 Ambient Assembly Repository

An ambient assembly repository should always be set up to ensure that the application reuses binary assembly reflection data whenever appropriate and that binary assembly references added to a project assembly are cached for future loading performance gains.

The ambient assembly repository should be set up in your application startup code as described in the Assemblies topic. The FileBasedAssemblyRepository class is the default implementation of an assembly repository, which supports the writing of binary assembly data to a cache folder specified in its constructor, as long as the application has read/write permissions to that folder.

protected override void OnStartup(StartupEventArgs e) {
	...
	// Use a path like this if in full trust; otherwise, pass null
	string appDataPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
		@"YourCompanyName\YourApplicationName\Assembly Repository");
	AmbientAssemblyRepositoryProvider.Repository = new FileBasedAssemblyRepository(appDataPath);
	...
}

Likewise on application exit, the assembly repository's cache should be pruned, also as described in the Assemblies topic.

protected override void OnExit(ExitEventArgs e) {
	...
	var repository = AmbientAssemblyRepositoryProvider.Repository;
	if (repository != null)
		repository.PruneCache();
	...
}

Configure the VBSyntaxLanguage and VBProjectAssembly

The next step is to create an instance of the VBSyntaxLanguage class and configure its project assembly.

This code creates a VBSyntaxLanguage, gets its default project assembly, and uses a background worker (for asynchronous execution) to add some assembly references, and queue up a source file to be included:

var language = new VBSyntaxLanguage();
var project = language.GetService<IProjectAssembly>();
var assemblyLoader = new BackgroundWorker();
assemblyLoader.DoWork += (sender, e) => {
	project.AssemblyReferences.AddMsCorLib();  // MsCorLib should always be added at a minimum
	project.AssemblyReferences.Add("System");
	project.AssemblyReferences.AddFrom(@"C:\MyAssembly.dll");
	project.SourceFiles.QueueFile(language, @"C:\MyFile.vb");
};
assemblyLoader.RunWorkerAsync();

Note that the IProjectAssembly.AssemblyReferences collection should be cleared when the project assembly will no longer be used. This cleans up any memory or resources in use by the assembly repository for loaded assemblies.

project.AssemblyReferences.Clear();

Use the VBSyntaxLanguage

Next, use the language on the ICodeDocument instances that will be editing Visual Basic code.

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

editor.Document.Language = language;

Documents Should Have an Appropriate FileName

It is a good practice to set the FileName on any document using the language to an appropriate value that uniquely identifies the document's contents. The filename is used as a key to register the types defined in the document with the language's IProjectAssembly.

If the filename is left empty, the add-on will fall back to using the document's unique ID (a GUID value) to identify its contents in the project assembly.

This code sets the filename for a document in a SyntaxEditor, whose instance is in the editor variable:

editor.Document.FileName = @"C:\Code.cs";

Assembly Requirements

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