xlsgen > overview > .NET best practices

If you are writing .NET code that targets xlsgen, you don't have to worry about anything in particular. But, to maximize the performance/benefits, here follows a couple of best practices for client-side code and server-side code.

For any .NET code

• use the COM-free deployment technique to never worry about COM component registration when you are deploying the software.
• if you update xlsgen by downloading a newer release, make sure to use an appropriate Interop.xlsgen.dll version. This file is produced by the .NET compiler, so rebuilding and redeploying is required.
• if you are willing to grant partial trust execution to xlsgen, you can do so by manually creating the Interop.xlsgen.dll file with the following command-line : tlbimp xlsgen.dll /keyfile:mykey.snk /out:Interop.xlsgen.dll, where mykey.snk is your private key pair. This file should replace the unsigned Interop.xlsgen.dll file automatically created by the Visual Studio environment when building your project.
• if you are willing to run xlsgen in multiple threads, your application may have to be marked as multithread-enabled. This is achieved by replacing the typical [STAThread] attribute near the main application function by [MTAThread]. At the end of this page is a sample multi-threaded code.

Client-side .NET code

• create an instance of the xlsgen engine as a class member instead of a local object. Doing so, this instructs the .NET garbage collector to avoid undue collection and potential disconnection.
• free the xlsgen instance by making a COM RCW method call : System.Runtime.InteropServices.Marshal.ReleaseComObject(engine);

Server-side .NET code

• if you are writing Excel files on the file system, make sure the target folder is granted write permissions. To do so, open the Microsoft IIS control panel, create a virtual folder, and make sure the "Write" checkbox is checked. Alternatively, if you'd rather avoid that, you can work with xlsgen only in memory.
• if you are using ASP.NET on a 64-bit OS, make sure to set it up as detailed here prior running xlsgen code.
• if you are using the same xlsgen engine instance across web pages, the best way to keep track of the instance is by using the built-in ASP(.NET) Session object map. You can take a look at the ASP.NET 2.0 online spreadsheet sample for an example of that.

Multithreaded code in .NET

xlsgen supports multi-threading, but that does not mean it's allowed to do crazy things. To be accurate, xlsgen is free-threaded, as opposed to thread safe. It means that the underlying engines are designed to work in parallel, following the classic document per worker thread model.

A typical multithreaded application has a main thread, and a number of worker threads.

Among practices are :

• the Start() bootstrap, which loads the component in memory and initializes it, should never be called more than once. Ideally, it's called in the main thread, and the resulting instance is passed around to all worker threads.
• the document per worker thread model means that ideally a worker thread works with the same workbook, from begin to end of the workbook lifecycle.
• with .NET, an application may have to mark itself as MTA enabled. Applications created by the Visual Studio project wizard usually have a [STAThread] marker near the application main function. Replace it with [MTAThread].

Here is a full example of multi-threaded code written with C# :

using System;
using System.Threading;
using System.Runtime.InteropServices;
using xlsgen;


namespace XlsGenMultithreading
{
    /// <summary>
    /// Summary description for Class1.
    /// </summary>
    class Class1
    {
        IXlsEngine engine;

        [DllImport("kernel32.dll")]
        static extern uint GetCurrentThreadId();

        [DllImport(@"C:\program files\xlsgen\xlsgen.dll")]
        static extern IXlsEngine Start();

        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [MTAThread]
        static void Main(string[] args)
        {
            Class1 c = new Class1();
            c.XlsgenMultithreading();
        }

        void XlsgenMultithreading()
        {
            engine = Start();

            for (int i = 0; i < 10; i++)
            {
                Thread t = new Thread(new ThreadStart(XlsgenWorkbook));
                t.Name = "thread" + i;
                t.Start();
            }
            Console.In.ReadLine();

            System.Runtime.InteropServices.Marshal.ReleaseComObject(engine);
        }

        void XlsgenWorkbook()
        {
            IXlsWorkbook wbk = engine.New( @"sample_" + Thread.CurrentThread.Name + "_" + GetCurrentThreadId() + ".xls" );
            wbk.StyleOption = xlsgen.enumStyleOption.styleoption_preserve;
            IXlsWorksheet wksht = wbk.AddWorksheet( "samplesheet" );
            wksht.set_Label(1,2, "Hello world!");
            wksht.set_ColWidth(2, 50);
            wbk.Close();
        }
    }
}