How it works - using Monitor-attribute Tutorial: Tokenization (manually) | Token
VisualBug released
March 2, 2015
Tutorial: Tracking (manually)
March 26, 2015

Tutorial: Tokenization (manually)

You probably will want to have automatic contexts for you application. As short explanation what contexts are: These are names that group tracked members together. Commonly this would be the parent class’ name. You can override the context manually (shown later) or you can set it automatically. In injection-mode this would be done by the injector once you leave the context null or empty. Then it would automatically fill in the parent class’ name. If you’re using Tokens independent of the mode (injection or manual) it would automatically use the token-generated context. How this works will be explained in a bit.

Tokens are markers for types. With them you can ensure that each instance of that type has it’s own unique identity. Of course this already applies by default, but it’s hard to track these instances. The token generates an unique ID and a name for each instance. With this you can both verify the identity as well as having a human-readable name for that instance. Tokens are required to track multiple instances inside of VisualBug. Since each instance has the same class name but have different values for tracked members this is required. Moreover do tokens serve the purpose of invalidation-verification. Once any tokenized instance has been destroyed it will automatically be noticed by VisualBug. Else this could take as long as you try to change a value (because normally VisualBug would only invalidate once the reference is gone – which anon will be checked on changes or value updates).

Another feature of tokens is that they can be used to implement patterns like the Singleton-pattern. You just have to set the corresponding token-type when you tokenize your class. At the moment there are two types of Tokens that are already implemented:

  • IncrementToken: This token increments the SimpleId (instance-index) by one everytime a new instance is being created. It names instances in a “Classname [SimpleId]” pattern.
  • SingletonToken: This token allows only one instance. If another one is being created while one is still existant, it will throw a TokenException. It names it’s instance like “Classname [SINGLETON]” or for static classes (which should use the SingletonToken by default since they only have one instance) “Classname [STATIC]”.

Usage & Implemenation

Implementing tokens isn’t much of a difficult task. You just have to mark the class as tokenized. Then you just need to set and unset it’s token in the constructor and in the destructor. That’s basically all you have to do.

We’ll take the TestClass3-class from the sample:

By applying the Tokenized-attribute, you can mark any class as tokenized thus allowing it to be automatically tokenized in injection-mode or having a slight little more comfortable code in manual-mode (doesn’t really matter, it’s more for compatiblity reasons). After that you need to set a variable to store your InstanceId. InstanceId is an object that specifies your instances’ IDs. It contains a GUID for an exact identification and an int for a human-readable ID. Moreover it has a method called GenerateName() which allows you to generate a readable name for this instance you can recognize amongst other instances.

Now you need to set up the constructor. In this case you need both. The static one and the non-static one (for static classes you can insert everything into the static constructor).

This step is required so that the class-type (TestClass3 here) is being registered. In injection-mode this would be automatically generated by using the Tokenized-attribute. You should always set this one because you then can easily swap between manual and injected.

NOTE: If you don’t use the Tokenized-attribute then you need to use the following overload of Spy.SetToken():

Now we will set up the constructor:

Always write this code at the top of the constructor. Especially if you’re using the SingletonToken. This ensures that no unallowed instancing can occur. You don’t necessarilly need to throw an exception. You could do whatever you want. In this example we throw one, because it can cause troubles during debugging if instances are not completely created and yet there is no exception being thrown. This would also be automatically generated by the injector.

Last but not least we need to set the destructor in order to unset the instance’ token correctly:

Static classes

For static classes you should always use the SingletonToken because these classes can’t have more than one instance. Every over token would just waste system resources. You can create your own token though. For static classes, just put everything into the static constructor. You won’t need any destructor because first it’s not possible to create one in static classes and second the instance won’t be collected. So you also won’t have to unset it’s token. This example is from TestClass2 out of our sample application:

This time we don’t throw an exception. Since this class is static, there won’t be any second constructor call. So it can’t happen that the token will be set twice and thus you won’t get any exception.

Further Tutorials

Now we’ve settled all that is needed for tokenization / instancing. You probably haven’t added any tracking code yet, so this would be your next step. Then you’ll be good to go for your first use of VisualBug.

Tutorial: Tracking (manually)

Zap
Zap
HTML Snippets Powered By : XYZScripts.com