Getting Started
This topic covers how to get started using the C# language from the .NET Languages Add-on, implemented by the CSharpSyntaxLanguage 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();
}
...
}
Note
Failure to set up an ambient parse request dispatcher when using the language will result in unnecessary UI slowdown since parse operations will be performed in the UI thread instead of in a worker thread.
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 (usually requires full trust). If the application is a sandboxed XBAP, it can pass null as the cache path instead.
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();
...
}
Note
Failure to set up an ambient assembly repository provider may result in unnecessary increased memory usages and slowdown when loading assembly references.
Configure the CSharpSyntaxLanguage and CSharpProjectAssembly
The next step is to create an instance of the CSharpSyntaxLanguage class and configure its project assembly.
This code creates a CSharpSyntaxLanguage, 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 CSharpSyntaxLanguage();
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.cs");
};
assemblyLoader.RunWorkerAsync();
Note
The Assemblies topic contains detailed information on the multiple ways (some not shown above) to add assembly references and source files to a project assembly.
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 CSharpSyntaxLanguage
Next, use the language on the ICodeDocument instances that will be editing C# code.
This code applies the language to a document in a SyntaxEditor, whose instance is in the editor
variable:
editor.Document.Language = language;
Note
We recommend reusing your CSharpSyntaxLanguage instance among all the documents in your application that are editing C# code. This saves on overall memory usage and reduces load times.
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 C# syntax language implementation in this add-on.
Assembly | Required | Author | Licensed With | Description |
---|---|---|---|---|
ActiproSoftware.Text.Wpf.dll | Yes | Actipro | SyntaxEditor | Core text/parsing framework for SyntaxEditor |
ActiproSoftware.Text.LLParser.Wpf.dll | Yes | Actipro | SyntaxEditor | LL parser framework implementation |
ActiproSoftware.Shared.Wpf.dll | Yes | Actipro | SyntaxEditor | Core framework for all Actipro WPF controls |
ActiproSoftware.SyntaxEditor.Wpf.dll | Yes | Actipro | SyntaxEditor | SyntaxEditor for WPF control |
ActiproSoftware.Text.Addons.DotNet.Wpf.dll | Yes | Actipro | .NET Languages Add-on | Core text/parsing for the C# language |
ActiproSoftware.SyntaxEditor.Addons.DotNet.Wpf.dll | Yes | Actipro | .NET Languages Add-on | SyntaxEditor for WPF advanced C# syntax language implementation |