CodeTrack: Writing your own plugins
CodeTrack has its own plugin system which allows you to extend it the way you want. Your plugins can also be shared with
others.
Plugins are usually based on one or more Deeptrace method rulesets, so please make sure you read about rulesets
first:
DeepTrace method rulesets
There are 2 main categories of plugins:
-
Viewplugins : giving you the possibility to visualize your traced data any way you want.
-
Valueplugins : these allow you to represent argument and return values in a custom way.
Note that you can combine one or more of any of these 2 type of plugins in the same assembly. In this documentation however,
there's just one type per assembly to keep things simple and clear.
Creating a viewplugin
- Go to the sample github page (
My Plugin github).
- Download the sample
- In the project properties, rename "MyPlugin.Plugins" to whatever you like (
just make sure the assembly ends with .plugins.dll for codetrack to find and load your plugin
- Choose a namespace of your liking
- Replace all 'MyPlugin' strings with the name you choose earlier
- Replace all 'MyNamespace' strings with the namespace you choose earlier
- In MyPlugin.cs, make sure to
replace the guid with a new one. This is necessary to uniquely identify your plugin (especially if
you want to share it later)
- Now build the project (make sure to restore the nuget packages)
- Now you should have a xyz.plugins.dll that you can place next to codetrack.exe or under the right version
in %localappdata%/codetrack/ (both work equally fine)
Note that your file should end with
.plugins.dll for codetrack to consider it a plugin assembly!
- Start Codetrack and go to the settings page and select 'plugins', now you should see your plugin.
- If you open a trace and go to the timeline view, your plugin should be listed with the 2 default plugins.
If all goes well you should see a clickable button
Congratulations, you now have a hello world plugin!
Of course that's not so useful just yet. To get some inspiration, the two plugins that are provided with CodeTrack
by default, are also available in Github :
CodeTrack.Plugins on github
Creating a valueplugin
- Go to the sample github page (
My ValuePlugin github).
- Download the sample.
- In the project properties, rename "MyPlugin.Plugins" to whatever you like (
just make sure the assembly ends with .plugins.dll for codetrack to find and load your plugin
- Choose a namespace of your liking
- Replace all 'MyPlugin' strings with the name you choose earlier
- Replace all 'MyNamespace' strings with the namespace you choose earlier
- In MyPlugin.cs, make sure to
replace the guid with a new one. This is necessary to uniquely identify your plugin (especially if
you want to share it later)
- Now build the project (make sure to restore the nuget packages)
- Now you should have a xyz.plugins.dll that you can place next to codetrack.exe or under the right version
in %localappdata%/codetrack/ (both work equally fine)
Note that your file should end with
.plugins.dll for codetrack to consider it a plugin assembly!
- The assembly you just built should already be useable: it contains just a simple valueplugin that replaces
values of type System.Uri by their string representation.
You probably want to implement something more exciting than this, so after testing the default behavior
you can just continue with the next steps to replace this with your own.
- If your plugin requires one or more specific rulesets, you can embed them in your plugin assembly (see:
Embedding rulesets)
If you don't want any rulesets, make sure to delete the sample .json file under the rulesets folder
- Now you are ready to start implementing the real functionality of your valueplugin: You can do this by replacing
the content of the CanConvert() and Convert() methods of your plugin.
- Start Codetrack and go to the settings page and select 'plugins', now you should see your plugin.
- If you open a trace which had methods traced that matched your ruleset, the arguments matching your value
plugin should now be presented the way you specified.
You can check this in the properties of a call or in the generic plugin.
Embedding rulesets
By embedding one or more rulesets, you can make sure that users can easily take a trace with the info that your plugin needs.
All embedded rulesets in plugin assemblies will autmatically be included in the ruleset library. To add a ruleset
just follow these simple steps:
- Create the ruleset you want by starting CodeTrack and configuring a new rulest in the deeptrace library (you
can find this under the setitngs tab). For More info on doing this check
Creating RuleSets
- Once you are happy with the ruleset (tip: test it first, by taking a trace and see if the trace contains
the info you expect), you can click on the copy link in the upper right corner of the library.
- Now go to your plugin project and add a json file. You can name it whatever you want, as long as it ends
with '.ruleset.json'.
- In that file you can now paste the content of your clipboard (this should be the json containing your ruleset).
- Make sure you set all 'IsReadOnly' fields to true (this way users won't be able to change your ruleset).
- Also fill in your information (author and authorcontact) if you really plan on sharing your plugin.
- Last step is to set the build action of the json file to 'Embedded resource'
- That's it! Your ruleset(s) should now be added to the library if you restart codetrack after you placed your
assembly next to the codetrack executable.