Create Your Own Report Connector

Transcription

1 Create Yur Own Reprt Cnnectr Last Updated: 15-December The URS Installatin Guide dcuments hw t cmpile yur wn URS Reprt Cnnectr. This dcument prvides a guide t what yu need t create in yur cnnectr cde. We'll use the XtraReprtsCnnectr as a starting pint. Creating A Reprt Cnnectr This is the entire versin 1.1 Reprt Cnnectr cde fr DevExpress XtraReprts, with cmmentary: /* * Cpyright (c) by VersaReprts, LLC. All rights, including the rights t cpy and distribute, are reserved. */ using System; using System.Cllectins.Generic; using System.Text; using System.Cllectins.Specialized; using VersaReprts.ReprtCnnectr; using System.IO; using System.Drawing; using System.Reflectin; using DevExpress.XtraReprts.UI; using DevExpress.XtraPrinting; using DevExpress.XtraReprts.Parameters; The abve highlighted lines are ging t change based n the requirements f the reprt designer that yu are using. The next sectin defines the reprt cnnectr class. The highlighted inheritance is required and prvides the prperties yu'll need t wrk with the reprt t be run. namespace XtraReprtsCnnectr public class XtraReprtsDllCnnectr : ReprtsCnnectrInterface /***** Public inherited prperties public string ReprtFileLcatin = Reprt file lcatin (if stred n disk); public byte[] ReprtFileCntents = Reprt cntents (if stred in database); public string[] ExtraDllsTLad = Full paths f extra DLLs t lad (if needed); public string ExtraInf = extra inf defined when reprt was cnfigured public string DataSurceInf = Data surce infrmatin (if needed); public string UserName = user name fr reprt's database cnnectin (if needed) public string Passwrd = passwrd fr reprt's database cnnectin (if needed) public string ReprtName = The reprt's name; public string ReprtDescriptin = The reprt's descriptin; public string ScheduleName = The name f the schedule using this reprt; public string SaveFrmat = The frmat f the reprt utput t generate (defined in the cnfiguratin files); public List<ReprtParameterValue> Parameters = list f reprt parameter values (include descriptin, type, and name f parameter in reprt) */ The prperties are listed in the cmments, but let's prvide sme mre depth:

2 ReprtFileLcatin - the lcatin that was selected by the reprt administratr fr the reprt file (e.g., the DLL r RPT file). If reprts f this type are stred in the database, this value will be the name f the file and yu are expected t use the reprt cntents stred as a byte array in ReprtFileCntents (see belw). If ReprtFileCntents is null, then yu are expected t use the reprt cntents stred at the lcatin specified by ReprtFileLcatin. ReprtFileCntents - the actual cntents f the reprt that the reprt administratr upladed when the reprt was defined t URS. If reprts f this type are stred n disk, this value will be null and yu are expected t get the reprt's cntents via the ReprtFileLcatin prperty. ExtraDllsTLad - an array f strings listing abslute paths t any DLLs that are ging t be needed t run a reprt f this type. This array gets set if the site administratr did nt lad these DLLs int the GAC. ExtraInf - this is the string prvided by the reprt administratr wh administers this reprt and is smething the reprt cnnectr writer will want t define. Fr example, if yur reprt is stred in a DLL, this prperty might define the fully qualified reprt class name t instantiate. DataSurceInf, UserName, Passwrd - these are used fr reprts that can vary their data surce (e.g., Crystal Reprts allws yu t change the data surce at run-time). The structure fr DataSurceInf -- like ExtraInf -- is defined by the reprt cnnectr writer; UserName and Passwrd are the user name and passwrd fr the data surce cnnectin and are specified nly if needed. ReprtName - the name f the reprt as defined by the reprt administratr when the reprt is created within URS. ReprtDescriptin - the descriptin string defined by the reprt administratr when the reprt is created within URS. ScheduleName - the name f the schedule defined by the reprt's scheduler when the reprt is scheduled within URS. SaveFrmat - this prperty is a string defining the finished reprt frmat t be created. The pssible chices are defined in the reprt_types.xml file fr each type f reprt that can be run by URS. Often, this prperty will cntain the file extensin fr the resulting reprt utput file (e.g., pdf); this string is limited t 10 characters. Parameters - a List f type ReprtParameterValue that cntains the parameters and values t be passed t the reprt as defined by the reprt scheduler fr this reprt. ReprtParameterValue is a class cntaining the fllwing prperties: Descriptin - the prmpt string used t request the value frm the reprt scheduler. ParameterNameInReprt - the string cntaining the parameter's name as specified in the reprt t be run. Type - an enumeratin which can be ne f Blean, Integer, Flat, String, Chices, Date_And_Time and specifies the type f parameter that was defined in URS (which might be a different type than the reprt's parameter needs, s yu'll want t be careful f that). Value - an bject cntaining the actual value t be passed t the reprt. The bject's value will match what the Type says it will be, with the exceptin that a Chices parameter results in a String value.

3 CreateReprt is the first rutine that yu will verride and is the main rutine t run a reprt: public verride bl CreateReprt(ut string errrmessages, ut byte[] results) errrmessages = string.empty; results = new byte[] ; string filename = string.empty; The first step is t get the reprt cntents int a place where yu can actually run them: if (ReprtFileCntents!= null) filename = Path.GetTempFileName(); File.Mve(fileName, Path.ChangeExtensin(fileName, Path.GetExtensin(ReprtFileLcatin))); File.WriteAllBytes(fileName, ReprtFileCntents); else filename = ReprtFileLcatin; catch (Exceptin ex) errrmessages = "Errr writing reprt DLL t a temprary file in XtraReprtDllCnnectr. Errr is: " + ex.message; return false; Sme reprt types will need t reside n disk t run, but might be stred in the database fr security and cntrl. If the reprt file is stred in the database but needs t run frm disk, use ReprtFileLcatin as the name f the resulting file and ReprtFileCntents as the cntents t be written int that file t run the reprt. Sme reprts can just be run directly frm memry, s either lad the reprt frm ReprtFileLcatin r use the byte array in ReprtFileCntents, whichever applies. If the reprt is stred n disk and runs frm there, just read ReprtFileLcatin t get the reprt. This cnnectr handles bth situatins: the reprt DLL stred in the database r the reprt DLL stred n the web server's disk. This particular reprt type is a DLL, s it is written t a temprary file and then laded by file name. At the same time, any additinal DLLs that aren't in the GAC that are defined in reprt_types.xml are als laded. The highlighted line belw shws that we are using ExtraInf as the name f the reprt class t instantiate. XtraReprt rpt = null; MemryStream mem = new MemryStream(); // Nw get the DLL assembly Assembly thisassembly = Assembly.LadFile(fileName); freach (string dll in ExtraDllsTLad) Assembly.LadFrm(dll); rpt = (XtraReprt)thisAssembly.CreateInstance(ExtraInf);

4 catch (Exceptin ex) errrmessages = "Errr lading reprt DLL r extra DLLs in XtraReprtDllCnnectr. Errr is: " + ex.message; return false; if (rpt == null) errrmessages = "Errr lading the class/methd fr this reprt. Was the reprt cnfigured crrectly fr the class/methd needed?"; return false; In the next sectin, we search fr the reprt parameters by name and assign values t them frm the Parameters list that was described abve. // If parameters defined fr reprt, then see if we can pass them if (Parameters.Cunt > 0) int parmspassed = 0; fr (int i = 0; i < rpt.parameters.cunt; i++) fr (int j = 0; j < Parameters.Cunt; j++) if (rpt.parameters[i].name.equals(parameters[j].parameternameinreprt, StringCmparisn.CurrentCultureIgnreCase)) rpt.parameters[i].value = Parameters[j].Value; parmspassed++; rpt.requestparameters = false; In the next sectin, we take the SaveFrmat value t determine the way t run/exprt the reprt. Fr the standard XtraReprtsCnnectr included with URS, SaveFrmat is the resulting file extensin and we use that t determine hw t run the reprt. XtraReprts allws us t save all resulting utput t a MemryStream, s we use that fr this cnnectr; ther reprt designers may nt have this feature, s yu will instead save the utput t disk and then read it back int memry. The end result f this step must be an array cntaining the reprt utput that is then passed back t the calling rutine fr string in URS. if (SaveFrmat.Equals("xls", StringCmparisn.CurrentCultureIgnreCase)) // Set XLS-specific exprt ptins. XlsExprtOptins xlsoptins = rpt.exprtoptins.xls; xlsoptins.shwgridlines = true; xlsoptins.usenativefrmat = true; // Exprt the reprt t XLS. rpt.exprttxls(mem); else if (SaveFrmat.Equals("pdf", StringCmparisn.CurrentCultureIgnreCase)) // Set PDF-specific exprt ptins. PdfExprtOptins pdfoptins = rpt.exprtoptins.pdf; pdfoptins.cmpressed = true; pdfoptins.imagequality = PdfJpegImageQuality.High; pdfoptins.dcumentoptins.title = ReprtName; pdfoptins.dcumentoptins.subject = ReprtDescriptin;

5 pdfoptins.shwprintdialgonopen = false; // Exprt the reprt t PDF. rpt.exprttpdf(mem); else if (SaveFrmat.Equals("html", StringCmparisn.CurrentCultureIgnreCase)) // Set HTML-specific exprt ptins. HtmlExprtOptins htmloptins = rpt.exprtoptins.html; htmloptins.exprtmde = HtmlExprtMde.SingleFile; htmloptins.title = ReprtName; rpt.exprtthtml(mem); else if (SaveFrmat.Equals("txt", StringCmparisn.CurrentCultureIgnreCase)) // Set TXT-specific exprt ptins. TextExprtOptins txtoptins = rpt.exprtoptins.text; txtoptins.separatr = ","; txtoptins.qutestringswithseparatrs = true; rpt.exprtttext(mem); else if (SaveFrmat.Equals("rtf", StringCmparisn.CurrentCultureIgnreCase)) // Set RTF-specific exprt ptins. RtfExprtOptins rtfoptins = rpt.exprtoptins.rtf; rtfoptins.exprtmde = RtfExprtMde.SingleFile; rpt.exprttrtf(mem); else if (SaveFrmat.Equals("tiff", StringCmparisn.CurrentCultureIgnreCase)) // Set Image-specific exprt ptins. ImageExprtOptins imgoptins = rpt.exprtoptins.image; imgoptins.exprtmde = ImageExprtMde.SingleFilePageByPage; imgoptins.frmat = System.Drawing.Imaging.ImageFrmat.Tiff; imgoptins.reslutin = 150; rpt.exprttimage(mem); else if (SaveFrmat.Equals("prnx", StringCmparisn.CurrentCultureIgnreCase)) rpt.createdcument(false); rpt.printingsystem.savedcument(mem); results = mem.tarray(); catch (Exceptin ex) errrmessages = "Exceptin detected running reprt in XtraReprtDllCnnectr: " + ex.message; return false; Make sure yu delete any files yu created befre exiting. The rutine returns true if the reprt ran successfully and the results cntains a byte array with the reprt's utput. Otherwise, the rutine returns false and sets errrmessages t cntain the errr messages t place int the URS lg fr assisting the reprt administratr with debugging what went wrng. finally if (filename.length > 0) // Delete the temp file cntaining the DLL

6 File.Delete(fileName); catch ; return true; The next rutine that yu can verride gets the list f parameters frm the reprt. Sme reprt designers will supprt this, thers will nt. If nt, yu dn't need t verride the rutine, because the base class handles this situatin prperly. The resulting List f type ReprtParameter cntains the infrmatin URS needs t schedule a reprt. ReprtParameter is a class with the fllwing prperties: Descriptin - the prmpt string used t request the value frm the reprt scheduler. Sme reprt types have a parameter descriptin separate frm the parameter name. Others d nt. ParameterNameInReprt - the string cntaining the parameter's name as specified in the reprt. Type - an enumeratin which can be ne f Blean, Integer, Flat, String, Chices, Date_And_Time and specifies the type f parameter t define in URS (which might be a different type than the reprt's parameter needs, s yu'll want t be careful f that). Yu shuld derive this value frm the type f parameter that is defined in the reprt (e.g., if the parameter in the reprt is a string, use String as the value fr Type). RangeLw - the minimum value that can be assigned by the scheduler t this parameter. This prperty nly applies t Integer and Flat parameter types. RangeHigh - the maximum value that can be assigned by the scheduler t this parameter. This prperty nly applies t Integer and Flat parameter types. Chices - sme reprt types supprt a list f chice strings fr a parameter and this array wuld be used t stre thse chice values. public verride List<ReprtParameter> GetReprtParameters(ut string errrmessage) errrmessage = string.empty; List<ReprtParameter> parms = new List<ReprtParameter>(); string filename = string.empty; string destinatinfilename = string.empty; XtraReprt rpt = null; Same setup as abve: we need t get t the reprt and lad all the necessary DLLs t cntinue. See the ntes abve fr specifics. if (ReprtFileCntents!= null) filename = Path.GetTempFileName(); File.Mve(fileName, Path.ChangeExtensin(fileName, Path.GetExtensin(ReprtFileLcatin)));

7 File.WriteAllBytes(fileName, ReprtFileCntents); else filename = ReprtFileLcatin; catch (Exceptin ex) errrmessage = "Errr writing reprt DLL t a temprary file in XtraReprtDllCnnectr. Errr is: " + ex.message; return null; MemryStream mem = new MemryStream(); // Nw get the DLL assembly Assembly thisassembly = Assembly.LadFile(fileName); freach (string dll in ExtraDllsTLad) Assembly.LadFrm(dll); rpt = (XtraReprt)thisAssembly.CreateInstance(ExtraInf); catch (Exceptin ex) errrmessage = "Errr lading reprt DLL r extra DLLs in XtraReprtDllCnnectr. Errr is: " + ex.message; return null; if (rpt == null) errrmessage = "Errr lading the class/methd fr this reprt. Was the reprt cnfigured crrectly fr the class/methd needed?"; return null; Fr each parameter fund in the reprt, create a ReprtParameter bject, fill in the apprpriate prperties, and then add it t the List. freach (Parameter field in rpt.parameters) ReprtParameter parm = new ReprtParameter(); parm.parameternameinreprt = field.name; if (field.descriptin == null field.descriptin.length == 0) parm.descriptin = field.name; else parm.descriptin = field.descriptin; switch (field.parametertype) case ParameterType.Blean: parm.type = ReprtParameterType.Blean; case ParameterType.DateTime: parm.type = ReprtParameterType.Date_And_Time; case ParameterType.String: parm.type = ReprtParameterType.String; case ParameterType.Decimal: case ParameterType.Duble: case ParameterType.Flat: parm.type = ReprtParameterType.Flat; parm.rangehigh = flat.maxvalue;

8 parm.rangelw = flat.minvalue; case ParameterType.Int32: parm.type = ReprtParameterType.Integer; parm.rangehigh = flat.maxvalue; parm.rangelw = flat.minvalue; parms.add(parm); catch (Exceptin ex) errrmessage = "Errr interpreting parameters in XtraReprtDllCnnectr. Errr is: " + ex.message; return null; Finally, dispse the reprt r delete any reprt files and return the parameters. finally if (rpt!= null) rpt.dispse(); if (filename.length > 0) // Delete the temp file cntaining the DLL File.Delete(fileName); catch ; return parms; Cmpile the cnnectr int a DLL as described in the URS Installatin Guide and place it n yur URS server in the bin directry fr the URS web site as well as the ReprtsRunner directry in the URS installatin. Hw des Reprt_Types.xml Wrk With This? Once yu have a reprt cnnectr, yu'll need t tell the reprt_types.xml file abut it. The structure f this file is described in the URS Installatin Guide, but we'll talk abut it in mre depth here. This is a typical reprt_types.xml created fr the DevExpress XtraReprts Reprt Cnnectr described abve: <?xml versin="1.0" encding="utf-8"?> <reprt_types> <reprt_type id="xtrareprtsdll" name="devexpress XtraReprts (DLL file)"> <cnnectr assembly="c:\versareprts\cnnectrs\xtrareprtscnnectr\bin\debug\xtrareprtscnnectr.dll" class="xtrareprtscnnectr.xtrareprtsdllcnnectr"/> <reprt_file extensins=".dll" strage="disk" extra_inf_prmpt="class Name f Reprt" pass_cnnectin="false" /> <supprting_assemblies>

9 v8.3\surces\devexpress.dll\devexpress.charts.v8.3.cre.dll" /> v8.3\surces\devexpress.dll\devexpress.data.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.utils.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.web.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.xtracharts.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.xtraprinting.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.xtrareprts.v8.3.dll" /> v8.3\surces\devexpress.dll\devexpress.xtrareprts.v8.3.web.dll" /> </supprting_assemblies> <utput_frmats> <frmat extensin="pdf" name="acrbat Reader" mime_type="applicatin/pdf" native="false" icn="images/pdf.png" /> <frmat extensin="html" name="html Web Page" mime_type="text/html" native="false" icn="images/html.png"/> <frmat extensin="rtf" name="rich Text File" mime_type="applicatin/rtf" native="false" icn="images/rtf.png"/> <frmat extensin="xls" name="excel 2003" mime_type="applicatin/vnd.ms-excel" native="false" icn="images/xls.png" /> <frmat extensin="prnx" name="preview-only Frmat" native="true" display_page="xtrareprtsviewer.aspx?id=0" icn="images/reprt.png" /> </utput_frmats> </reprt_type> </reprt_types> Let's tie sme pieces tgether nw. In this line, the name attribute is what appears in the Reprt Definitin Wizard when a reprt administratr selects this type f reprt. <reprt_type id="xtrareprtsdll" name="devexpress XtraReprts (DLL file)"> This line cntains the reprt cnnectr's cmpiled assembly lcatin and the class defined in it: <cnnectr assembly="c:\versareprts\cnnectrs\xtrareprtscnnectr\bin\debug\xtrareprtscnnectr.dll" class="xtrareprtscnnectr.xtrareprtsdllcnnectr"/> The fllwing line defines sme additinal infrmatin that makes it pssible fr URS t prperly call and run a reprt f this type: <reprt_file extensins=".dll" strage="disk" extra_inf_prmpt="class Name f Reprt" pass_cnnectin="false" /> In the abve line, the extensins are the list f extensins that are acceptable fr a reprt f this type. XtraReprts als supprts a reprt frmat that can be sent withut cding (RPX frmat), but we didn't use that fr this cnnectr, s the extensins are nly ".dll". Because we're using DLL-based reprts fr this cnnectr, we need t knw the fully-qualified class name f the reprt in the DLL that is ging t be prvided t the Reprt Definitin Wizard.

10 The <supprting_assemblies> blck defines the array f strings that end up in the ExtraDllsTLad prperty that's inherited by the Reprt Cnnectr class yu create. The <utput_frmats> blck is critical and defines everything yu'll need t knw when yu generate the reprt in yur cnnectr rutines. Let's lk at tw f the lines and see why this is s critical: <frmat extensin="xls" name="excel 2003" mime_type="applicatin/vnd.ms-excel" native="false" icn="images/xls.png" /> <frmat extensin="prnx" name="preview-only Frmat" native="true" display_page="xtrareprtsviewer.aspx?id=0" icn="images/reprt.png" /> In these lines, the extensin attribute is a value that culd be placed int the SaveFrmat prperty that the class inherits. Fr exprted frmats that dn't require a special viewer page (e.g., Excel, PDF), yu will set the native prperty t "false". Fr frmats that have a "native" viewer (e.g., XtraReprts includes a viewer cntrl that yu can embed in a web page), the native prperty will be set t "true" and the reprt will be saved in a frmat that's "native" t this viewer. Hw Shuld I Debug My Reprt Cnnectr? Once yu have the reprt cnnectr cde cmpiled, we recmmend that yu test the cde with ReprtsRunner perating in interactive mde. If ReprtsRunner has been started as a service, temprarily stp the service and run ReprtsRunner frm a Cmmand Prmpt windw. Then use Visual Studi t attach t the ReprtsRunner prgram and debug yur cnnectr as needed. Cpyright 2009, by VersaReprts, LLC. All rights -- including the right t cpy, distribute, r disseminate -- are reserved.