Tutorial 17 - Designtime, Runtime and License Requirements
Contents
TeeChart Runtime Requirements TeeChart runtime Files
Runtime Editor Help support
Configuration
TeeChart Language Support
Configuration
Design time Language
TeeChart Custom Theme Support
ASP.NET application support
Configuration
Licensing setup for design and runtime
Description
Operational considerations
Using TeeChart in a dll
Using TeeChart in a plugin dll
Using TeeChart in VC++
Runtime distribution
Troubleshooting Licensing Issues
TeeChart runtime requirements
This tutorial looks at some aspects of runtime installation for your TeeChart application. TeeChart runtime Files
Your TeeChart application will need to be distributed with the TeeChart.dll and, if your application uses the Steema.TeeChart.Languages namespace, with the TeeChart.Languages.dll. You need to decide here whether to install these dlls locally, for example, in a bin directory underneath your application directory, register the folder in the AssemblyFolders registry key, or to install them in the Global Assembly Cache (GAC). Please follow this link to read up on how the GAC can facilitate the sharing of your TeeChart .Net Assembly between a number of different applications.
Runtime Editor Help support
TeeChart's Editor may be implemented at runtime to enable your application users to modify Chart settings. TeeChart's own designtime programmer help does not extend to runtime but you have the option to add your own helpfile to be opened by the Help button on the Chart Editor at runtime. Configuration
[HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\HTML Help]
"YourHelpfile.chm"="drive:\directory"
TeeChart Language Support
TeeChart languages, that is, the ability to display the TeeChart Editor and other TeeChart dialogs in differing languages, is presently only supported for runtime. Configuration
To change a language at runtime you simply have to use code similar to the following:
Steema.TeeChart.Languages.German.Activate();
Example
Here populating a Combo box to use for language selection:
private void Form1_Load(object sender, System.EventArgs e)
commander1.Chart = tChart1;
tChart1.Aspect.View3D = false;
line1.FillSampleValues(20);
comboBox1.Items.Add("Arabic");
comboBox1.Items.Add("Brazilian");
comboBox1.Items.Add("Catalan");
comboBox1.Items.Add("Chinese Simple");
comboBox1.Items.Add("Chinese Traditional");
comboBox1.Items.Add("Danish");
comboBox1.Items.Add("Dutch");
comboBox1.Items.Add("English");
comboBox1.Items.Add("Finnish");
comboBox1.Items.Add("French");
comboBox1.Items.Add("Galician");
comboBox1.Items.Add("German");
comboBox1.Items.Add("Hebrew");
comboBox1.Items.Add("Hellenic");
comboBox1.Items.Add("Hungarian");
comboBox1.Items.Add("Indonesian");
comboBox1.Items.Add("Italian");
comboBox1.Items.Add("Japanese");
comboBox1.Items.Add("Korean");
comboBox1.Items.Add("Norwegian");
comboBox1.Items.Add("Polish");
comboBox1.Items.Add("Portuguese");
comboBox1.Items.Add("Russian");
comboBox1.Items.Add("Slovak");
comboBox1.Items.Add("Slovene");
comboBox1.Items.Add("Spanish");
comboBox1.Items.Add("Swedish");
comboBox1.Items.Add("Turkish");
comboBox1.Items.Add("Ukranian");
comboBox1.SelectedItem = "English";
private void comboBox1_SelectedIndexChanged(object sender, System.EventArgs e)
switch(comboBox1.SelectedIndex)
case 0: Steema.TeeChart.Languages.Arabic.Activate(); break;
case 1: Steema.TeeChart.Languages.Brazilian.Activate(); break;
case 2: Steema.TeeChart.Languages.Catalan.Activate(); break;
case 3: Steema.TeeChart.Languages.ChineseSimp.Activate(); break;
case 4: Steema.TeeChart.Languages.ChineseTrad.Activate(); break;
case 5: Steema.TeeChart.Languages.Danish.Activate(); break;
case 6: Steema.TeeChart.Languages.Dutch.Activate(); break;
case 7: Steema.TeeChart.Languages.English.Activate(); break;
case 8: Steema.TeeChart.Languages.Finnish.Activate(); break;
case 9: Steema.TeeChart.Languages.French.Activate(); break;
case 10: Steema.TeeChart.Languages.Galician.Activate(); break;
case 11: Steema.TeeChart.Languages.German.Activate(); break;
case 12: Steema.TeeChart.Languages.Hebrew.Activate(); break;
case 13: Steema.TeeChart.Languages.Hellenic.Activate(); break;
case 14: Steema.TeeChart.Languages.Hungarian.Activate(); break;
case 15: Steema.TeeChart.Languages.Indonesian.Activate(); break;
case 16: Steema.TeeChart.Languages.Italian.Activate(); break;
case 17: Steema.TeeChart.Languages.Japanese.Activate(); break;
case 18: Steema.TeeChart.Languages.Korean.Activate(); break;
case 19: Steema.TeeChart.Languages.Norwegian.Activate(); break;
case 20: Steema.TeeChart.Languages.Polish.Activate(); break;
case 21: Steema.TeeChart.Languages.Portuguese.Activate(); break;
case 22: Steema.TeeChart.Languages.Russian.Activate(); break;
case 23: Steema.TeeChart.Languages.Slovak.Activate(); break;
case 24: Steema.TeeChart.Languages.Slovene.Activate(); break;
case 25: Steema.TeeChart.Languages.Spanish.Activate(); break;
case 26: Steema.TeeChart.Languages.Swedish.Activate(); break;
case 27: Steema.TeeChart.Languages.Turkish.Activate(); break;
case 28: Steema.TeeChart.Languages.Ukrainian.Activate(); break;
Design time Language
TeeChart can set a default designtime Language that will take effect immediately when TeeChart is added to a Form. The Language active in the language key will take effect or the language may be set via the Chart right-mouseclick menu 'Options' option the first time you open the Chart project.
Ie.
[HKEY_LOCAL_MACHINE\SOFTWARE\Steema Software\TeeChart.NET]
"Language"=dword:00000011 //Hex 11 is decimal 17 (Japanese)
ASP.NET application support
This section includes information relevant to the distribution of ASP.NET WebForm applications.Configuration
WebChart uses registry settings to locate a temporary chart storage folder only when WebChart's TempChart property has been set to 'File'. If the WebChart's TempChart property is set to 'Session' no registry entries are required in the runtime server. Please refer to Tutorial 9, ASP.NET Applications, for more information about WebChart application configuration.
When TempChart is set to File:
The File setting should be used if you wish to write temporary files to disk. By default, when TeeChart is installed, it creates registry keys with the temporary file location and equivalent virtual folder name. The keys are as follows:
[HKEY_LOCAL_MACHINE\SOFTWARE\Steema Software\TeeChart.NET]
"VirtualShare"="/TeeChartForNET"
"ShareFolder"="C:\Program Files\Steema Software\TeeChart for .NET v3\TeeChartForNET"
The above settings are as would be created in a standard English Language machine if default install locations are accepted. The TeeChartNET virtual folder is created by the TeeChart installer. You may change these registry settings provided you create the necessary IIS Virtual Share location to reflect the new registry value.
WebChart saves files to a folder called _Chart_tmp below the folder named in the ShareFolder registry key.
Temporary files are not deleted by TeeChart though a utility may be included for you to do so automatically as a Windows scheduled task, please check TeeChart inclusions with the current version.
Licensing setup for design and runtime
This section describes configuration elements and setup steps to be taken to comply with the TeeChart designtime and runtime licensing architecture.Description
TeeChart uses license control based on Microsoft's System.Component.LicenseProvider class. When TeeChart is installed via the TeeChart installer a registry license key is added, the visible portion of which can be seen under the HKEY_LOCAL_MACHINE\SOFTWARE\Steema Software\TeeChart.NET key as:
"DesignKey"="Steema.TeeChart.TChart is a licensed component."
The presence of the key, plus the corresponding 'not-published' keycode allows TeeChart to be used at designtime in Visual Studio.NET and permits the key to be compiled into runtime executable (.exe) and library (.dll) files so that the TeeChart.dll and TeeChart.languages.dll files may be distributed with compiled applications but without offering the option for TeeChart to be used as a designtime component at the installed location.
Operational considerations
A project that includes a TChart, Chart or WebChart component must include a Licenses.licx file. That file is automatically added to a TChart (Windows Form Chart) or WebChart (Web Form Chart) project by the Visual Studio IDE when either chart is added to it. In the case of a non-designtime Chart application, for example where the Chart is manually created at runtime as
"Steema.TeeChart.Chart c = new Steema.TeeChart.Chart();", then you must manually add the licenses file to the project, an example file that you may use is included in the Utils folder. You can add it by selecting the project in the VS.NET Solution Explorer and right mousebutton clicking for 'Add | AddExisting Item' with File type 'All files' and selecting 'Utils\Licenses.Licx'.
Using TeeChart in a dll
If you have successfully compiled TeeChart with license into a dll, please note that if you then use that dll in another application you need to be sure to add the TeeChart license lines to the Licenses.licx file of the final application even though that application may not itself have a direct reference to TeeChart. If your end-user application is not developed in Visual Studio .NET then the license file and license itself should not be necessary at the point of final compilation.
If you are working in an environment in which re-use of your dll won't take place at a machine with a Developer license please confirm whether re-use might fall into the bounds of 'plugin use' as described in the following section, Using TeeChart in a plugin dll. If you feel that your assembly (that uses TeeChart) needs to be re-used by a container that has knowledge of TeeChart classes and methods or needs to reference the assembly, but at a machine that doesn't have a TeeChart Developer License then please confirm that the machine in question is licensed to use TeeChart at designtime. Some distribution or groupwork circumstances may need to be resolved via a special license condition, Steema personnel at info@steema.com can help with license enquiries.
Using TeeChart in a plugin dll
The standard version of TeeChart for .NET supports license control for use in a dynamically loaded plugin. The plugin would typically be an assembly that contains TeeChart and that may be loaded dynamically at runtime by a container application using the NET 'Assembly.Load' method or similar. To permit the container application to load and run TeeChart without requiring a licenses.licx file at container level TeeChart offers an alternative to default constructor by which the dll assembly in which it is compiled passes itself as an argument and license checks are made at the level of the dll not at the container application. Please note that the container application may not make code calls directly to TeeChart. It may open and run the TeeChart dll whilst that dll is autonomous in nature, making its own calls to TeeChart. The exception to that rule, allowing Chart calls to be made from the container application, would be if methods of TeeChart are 'wrapped' (secondarily called) by methods that may be defined in an independant interface. The example described here could be modified to include such calls.
The plugin
The plugin that houses TeeChart would load TeeChart passing itself as argument when created. The overloaded constructor need only be used the first time that TeeChart is opened, to permit the license check to take place. Thereafter TeeChart may be used via conventional means. An example of use would be the following. In this example a 'dummy' creation of TeeChart is made at form create to force the initial license check.
Example:
In this example, PluginShared.Factory is an interface, referenced by the host application, that offers up a method called 'CreateForm'. The Assembly that houses TeeChart implements PluginShared.Factory and thus also offers up the CreateForm method but with its own implementation (in which it loads TeeChart). The host recognises the CreateForm method call without requiring knowledge of the TeeChart specific assembly.
Please note. The Assembly that houses TeeChart must contain a Licenses.licx file and be compiled on a machine with a valid TeeChart Developer License.
Assembly housing TeeChart (eg. PluginWithTeeChart.dll)
-------------------------------------------------------------------------------------------
Class:
namespace Plugin
{
public class FactoryImpl : PluginShared.Factory
{
public System.Windows.Forms.Form CreateForm()
{
try
{
return new PluginWithTeeChart.FormWithChart();
}
catch (Exception e)
{
MessageBox.Show("failed to create plugin with error: " + e.ToString());
return null;
}
}
}
}
Form:
namespace PluginWithTeeChart
{
public partial class FormWithChart : Form
{
public FormWithChart()
{
//discardable Chart forces License check
Steema.TeeChart.TChart tempChart = new Steema.TeeChart.TChart(this);
tempChart = null;
InitializeComponent(); //<---- Normal application code. Could run here various TeeCharts without need for overloaded constructor
}
}
}
The container application (eg. HostApp.exe)
----------------------------------------------------------------------
The container might load the TeeChart housing assembly (dll) in the following way. It is important that HostApp reference the common interface Plugin.FactoryImpl that publishes the CreateForm method.
void LoadTeeChartPlugin(string pluginName)
{
string pluginName = @".dll";
try
{
Debug.WriteLine("Loading plugin assembly " + pluginName);
Assembly assembly = Assembly.LoadFrom(pluginName);
string factoryTypeName = "Plugin.FactoryImpl";
Type t = assembly.GetType(factoryTypeName);
if (t == null)
{
MessageBox.Show("Type: " + factoryTypeName + " not found in plugin assembly");
return;
}
PluginShared.Factory factory = (PluginShared.Factory)assembly.CreateInstance(t.ToString());
System.Windows.Forms.Form f = factory.CreateForm();
f.ShowDialog();
}
catch (Exception ex)
{
MessageBox.Show(ex.ToString());
}
}
Using TeeChart in Visual C++.NET
The implementation of licensing in VC++ is not quite as transparent as it might hope to be for other .NET programming languages. You can successfully implement licensing for VC++ projects by following the steps described by by Tim Adler on the microsoft.public.dotnet.framework newsgroup.
Quote:
"My workaround is simple: Create a new solution, and within that a new C# project, with the SAME application name as your C++ application. Create a dummy form and drop each of the components needing licensing onto this form. Or alternatively, edit the licenses.licx file that is automatically generated to refer to each of the components. Then build the application. Then navigate to the debug directory and copy the "*.licenses" file into the base directory of your C++ application. Then under the Project Options->Linker->Input->Embed Managed Resource File setting of your C++ app, refer to this license file. Then do a 'rebuild'."
Licenses.licx file
The file is a text file that should contain at least one or to serve as a generic file, all of the following three lines:
Steema.TeeChart.Chart, TeeChartThe content should include at least the name of the class created by your project, typically Steema.TeeChart.TChart for a Windows Form based project, Steema.TeeChart.Chart for a project in which you create the Chart by code and Steema.TeeChart.Web.WebChart for a WebForm project that includes TeeChart's WebChart component.
Steema.TeeChart.TChart, TeeChart
Steema.TeeChart.Web.WebChart, TeeChart
When a Chart is added to a Form NET automatically adds a slightly longer version, also correct, that includes the assembly version number and public key.
Steema.TeeChart.TChart, TeeChart, Version=1.1.1864.22788, Culture=neutral, PublicKeyToken=9c8126276c77bdb7
Adding license support to older 'non-licensed' projects
Note that for Form applications created with a previous version of TeeChart, where the Licenses file does not exist you can quickly generate it by dragging a Chart from the Steema section of the Tool palette onto any of the project's forms, and afterwards deleting it. The newly dragged Chart provokes the IDE into adding the Licenses.licx file.
Runtime distribution
A project's .exe or .dll, having been compiled with the Licenses.licx file, may be distributed as a runtime application along with the TeeChart.dll (and TeeChart.Languages.dll file if required) without the need for any TeeChart runtime license file or registry key to be installed.
Troubleshooting Licensing Issues
Possible error scenarios that we have seen are:
- Error message when compiling:
"Could not transform licenses file 'licenses.licx' into a binary resource."A likely cause for this is that the Development License registry keys are not in place. Please check for the visible key entry described in this chapter to see if there are any obvious problems or ommissions in it. An option to resolve the issue would be to use the TeeChart installer to re-install TeeChart, the installer sets the registry keys. If the problem persists please contact TeeChart support via the support forums.
- License error when trying to run compiled (runtime) output application on machine without designkey installed.
Check that the project includes the Licenses.licx file. It may have been added automatically when adding a Chart to a Form or it may have been added manually. In either case please confirm that the Licenses.licx file exists in your project as an embedded resource. You will need to activate 'Show all files' to see the presence of Licenses.licx in the project's Solution Explorer window.
- Another possible cause for the issue is that the licenses.licx file content is incorrect. Please check that the content reflects that described in a previous part of this chapter.
How to specify custom themes for designtime and runtime
Custom themes are small *.xml files which can be created by a simple line of code: tChart1.Export.Theme.Save(@"C:\Steema\MyTheme.xml");This custom theme encapsulates a number of Chart graphical settings relating to the font, brush and pen color and style of the Panel, Axes, Headers, Footers, Legend etc. Once created, these themes can be displayed in the Chart Editor's Theme tab with the name appearing there as the name given to the file. So that the Chart Editor knows where to look for these files, there is a registry setting which specifies a folder on the local machine:
[HKEY_LOCAL_MACHINE\SOFTWARE\Steema Software\TeeChart.NET]By simply adding your custom themes (*.xml files) to the folder specified in this key the Chart Editor will read and display them.
"ThemeFolder"="C:\Program Files\Steema Software\TeeChart for .NET v3\Themes"
See Also
TeeChart Pro .Net Tutorials:Contents:Tutorial9 - ASP.NET Applications