FastReport.Mono. Part 1: Run a demo web report
- From the sandbox
- Tutorial
Due to the fact that the official documentation of FastReport.Mono is outdated, and it is not even clear which version of the Debian distribution it belongs to (I can assume that it is 6 or younger), I decided to write more or less sane instructions for installing a demo Web interface for viewing reports.
The problem arose because of the looming prospect of moving one of the projects where FastReport.Net was used, from Windows + Oracle to Linux + PostgreSQL. In addition, I was interested in the possibility of implementing everything in the form of microservices in Docker containers. Alas, “it was smooth on paper, but forgot about the ravines”: I had to face a number of nuances that I will try to describe in more or less detail and suggest possible solutions to problems.
In the process, I took notes-reminders for myself in the project wiki, and only then I tried to systematize everything. As a result, I got a lot of text, I’ll try to divide the publication, tentatively, into three parts:
NB The whole following text is not a step-by-step guide to action, but possible solutions to problems (sometimes more than one way). Accordingly, I advise you to immediately read all the material, and then choose the appropriate installation method.
And so, the first thing I would like to pay attention to is package names and dependency problems. If you plan to use Debian 8 (Jessie), then be prepared for the need to install Mono from the Mono-project repository or even build from source. The official Jessie repositories lack some packages, such as libapache2-mod-mono. I did not begin to do this, so all the research was done on Debian 9 (Stretch). I strongly do not recommend installing the package with ASP.Net examples - asp.net-examples, as during the installation process, an inclusion will be added to the Apache config containing uniform Mono settings for all virtual hosts, a universal alias / samples will also be added.
Second: when using the Apache virtual host configuration file from a publication on the official developers blog, note that it is written for Apache 2.2 and does not quite fit Apache 2.4. The problem lies in changing the configuration of directory permissions, which appeared in version 2.4: in the old config there is no Require all granted in the Directory section. In addition, some changes to the Mono settings are possible: something can be omitted because corresponds to the default values, but something may not be right for you. In principle, to launch a demo project, you can omit almost everything. And, of course, depending on the chosen configuration, setting environment variables or access rights to files and directories.
The third, and very interesting point, is that for proper operation it is necessary either to change the directory structure, not doing dumb copy-paste lines from the example, but having studied another post (why the authors did not combine the two entries into one is a mystery to me). Or set the environment variable MONO_PATH so that it looks in the directory with the FastReport. *. Dll files and correct web.config.
The fourth, and the most controversial and interesting point - for the operation of FastReport.Web in some cases you need Xs (X11). For example, a demo project with barcodes requires System.Windows.Forms. And, if there are no special problems when starting the server on behalf of the user logged in via the GUI, then in cases when the project is launched via SSH, Apache or the Docker container will need to configure environment variables, and in the case of containers, it will also need to "forward" the X server from the outside.
The fifth point will consider the process of assembling connectors for some popular DBMSs. This is due to the fact that with FastReport (both Windows and Mono versions), plug-ins for using the DBMS are delivered in the form of source texts, and not ready-to-use libraries. Will have to collect manually.
But first things first. I assume that the system is already installed, and it is not completely empty - it has your favorite text editor and archiver.
If you believe the official manual, then the installation should not take much time; everything should go smoothly through apt. Well, let's get started. Install Mono, the XSP web server, the Apache web server, and the module that allows you to run ASP.Net applications through Apache.
Next, download and unpack the demo project. Hereafter, I will specifically use paths other than / var / www. First of all, this allows you to find errors in the configuration or even in the project itself. And secondly, the placement of third-party software products in / opt corresponds to the purpose of this directory.
Figure 1. Launch XSP
XSP - a lightweight web server for APS.Net, written in C # and allows you to quickly and easily test simple applications. If you believe the documentation and the advice of experienced - it is not recommended for use in a combat environment. By default, the XSP listens on port 9000 and all network adapters (IP 0.0.0.0). This procedure will show us whether in principle at least something works. I can assume that you will get some kind of exception. Alas, the authors of such a seemingly interesting tool for generating reports did not take care of the convenience of installing demonstration materials.
Fig. 2. A possible error message (the picture is clickable)
This problem is due to the fact that Mono cannot find the FastReport.Web.dll library. Moreover, the error occurs even if the file is copied to htdocs. I am not a specialist in .NET, and even more so in Mono. And I didn’t read the link to the post on the authors’ blog in the introduction right away (by the way, there is a question - why isn’t this emphasis, for example, file names are highlighted in bold instead of a directory?). According to this, I had to smash my head. The first possible solution is to copy the DLL to the current directory and set the environment variable MONO_PATH :
But here, too, failure awaits. Most likely, you received an exception that the namespace or type FastReport.Utils was not found. The problem can be solved - just register FastReport.Mono.dll in web.config.
Fig. 3. Compilation error - the Utils type or namespace was not found (the picture is clickable)
Add a dependency - in the web.config section, write the following line:
The version number and token may differ; at the moment, such are relevant. You can get a token from dll like this:
Check the version number as follows:
The result of all our torment should be more or less sane display of the page with a demo report.
Fig. 4. Not quite working example
Alas, something went wrong. It was assumed that the browser window will have barcodes, as in the screenshot in the official FastReport.Mono manual. You may not have this error; I’ll tell you a bit about the reasons for its occurrence and the way to eliminate it.
In the meantime, back to the libraries. In the process of writing the instructions, another way was found to solve the problem with connecting FastReport.Web.dll and FastReport.Mono.dll (Figures 2 , 3), although, probably, .NET developers would have done that right away. It is enough to create the htdocs / bin directory and move FastReport.Web.dll and FastReport.Mono.dll there. There is no need to edit web.config and change MONO_PATH, Mono finds everything and throws no exceptions. Good or bad, it's hard to say. In principle, if everything is hidden behind the frontend in the face of Apache, then the directory with dlls can be hidden from prying eyes. The directory structure for this solution is shown in Figure 5.
Fig. 5. Demo project directory tree
The sample web report in the dependency list contains System.Windows.Forms. If you looked in web.config, then I think you paid attention to the line:
If you encounter the problem shown in screenshot 4 or in the console you see the message “No protocol specified”, then there is one of the following options:
In the first case, you need to install / run X. Options 2 and 3 are essentially similar, and the problem is solved by setting environment variables DISPLAY , and possibly XAUTHORITY . The only difference is that if the OS was originally installed with a graphical environment, the user has the XAUTHORITY variable set and looks at the ~ / .Xauthority file, but the root does not. In principle, it is enough to do the following before starting XSP:
For root, you need to add:
Actually, running something on behalf of the superuser is a bad idea, but if you really want to ... In addition, setting the XAUTHORITY variable is still useful when configuring Apache to allow the www-data user to use the X server (relevant if during the installation of Debian graphic environment packages were selected). If the OS was initially installed in the minimum version, everything will be slightly different, because Xorg may very well be installed without a display manager. Or not installed at all.
If you are faced with the need to “wrap” FastReport.Mono in a container and decide to observe the principle of “1 service - 1 container”, you will have to create a container with an X server and “forward” the socket between the containers. You will have to use the Dummy display driver as a video driver. This configuration will be discussed in one of the following parts of the manual.
An alternative option for Linux / Unix users may be to forward the X server from the host OS (tcp or unix socket). To get this feature on MacOS, you need to install XQuartz .
In principle, setting up Apache 2.4 and mod_mono does not require any special tricks. If, suddenly, you did not follow my advice and installed the asp.net-examples package, I recommend that after testing the mod_mono functionality comment out the following line in
/etc/apache2/mods-available/mod_mono.conf:
Otherwise, the alias / samples will be nailed to all your virtual hosts, by which the very examples of using ASP.Net will be opened. In addition, Apache can swear in logs and when restarted that mod_mono is already loaded. This is due to the fact that two modules are loaded - mod_mono and mod_mono_auto (for automatic deployment of applications). Mod_mono_auto can be safely disabled:
The virtual host configuration file from the official documentation is redundant in settings and in some places is not relevant. The minimum required configuration can be viewed under the spoiler.
Actually, we put everything in /etc/apache2/sites-available/001-mono.conf using our favorite text editor, turn on the site and restart Apache:
Parsing the entire config does not make deep sense, however, I would like to dwell on one line in more detail:
This is a very noble crutch that allows you to solve 2 problems at once. I already described one of them in the section devoted to System.Windows.Forms- the application needs to specify DISPLAY. The second point is related to the fact that during the compilation and execution of the application, the directories ~ / .local and ~ / .mono are used, and the user www-data, which runs Apache, has his / her / home directory / var / www. I figured it’s not worth littering the entire system. In principle, it works. Of course, one could try changing the user and group for this particular virtual host, but it didn’t take off. As I understand it, mod_mono starts the server from an Apache user and when trying to use mpm_itk nothing worked, because The Apache process does not have access to the Monix server's UNIX socket. It is possible that the problem can be solved using FastCGI, but have not tried it, I do not pretend to be true.
The final touch is to give www-data user access to the X server. And here we can use the ability to install XAUTHORITY for superuser.
I would like to draw attention to the fact that the changes made when xhost is called will be active only until the shutdown / reboot. If you use lightdm, then it makes sense to wrap this construct in a script and set it to autostart by adding the line display-setup-script = / path / to / script.sh in /etc/lightdm/lightdm.conf. Alternatively, you can change / etc / X11 / xinit / xinitrc.
Fig. 6. Workable example through Apache 2.4
The problem arose because of the looming prospect of moving one of the projects where FastReport.Net was used, from Windows + Oracle to Linux + PostgreSQL. In addition, I was interested in the possibility of implementing everything in the form of microservices in Docker containers. Alas, “it was smooth on paper, but forgot about the ravines”: I had to face a number of nuances that I will try to describe in more or less detail and suggest possible solutions to problems.
In the process, I took notes-reminders for myself in the project wiki, and only then I tried to systematize everything. As a result, I got a lot of text, I’ll try to divide the publication, tentatively, into three parts:
- Running a demo report
- Using FastReport in Docker Containers
- DB connection
NB The whole following text is not a step-by-step guide to action, but possible solutions to problems (sometimes more than one way). Accordingly, I advise you to immediately read all the material, and then choose the appropriate installation method.
Introduction
And so, the first thing I would like to pay attention to is package names and dependency problems. If you plan to use Debian 8 (Jessie), then be prepared for the need to install Mono from the Mono-project repository or even build from source. The official Jessie repositories lack some packages, such as libapache2-mod-mono. I did not begin to do this, so all the research was done on Debian 9 (Stretch). I strongly do not recommend installing the package with ASP.Net examples - asp.net-examples, as during the installation process, an inclusion will be added to the Apache config containing uniform Mono settings for all virtual hosts, a universal alias / samples will also be added.
Second: when using the Apache virtual host configuration file from a publication on the official developers blog, note that it is written for Apache 2.2 and does not quite fit Apache 2.4. The problem lies in changing the configuration of directory permissions, which appeared in version 2.4: in the old config there is no Require all granted in the Directory section. In addition, some changes to the Mono settings are possible: something can be omitted because corresponds to the default values, but something may not be right for you. In principle, to launch a demo project, you can omit almost everything. And, of course, depending on the chosen configuration, setting environment variables or access rights to files and directories.
The third, and very interesting point, is that for proper operation it is necessary either to change the directory structure, not doing dumb copy-paste lines from the example, but having studied another post (why the authors did not combine the two entries into one is a mystery to me). Or set the environment variable MONO_PATH so that it looks in the directory with the FastReport. *. Dll files and correct web.config.
The fourth, and the most controversial and interesting point - for the operation of FastReport.Web in some cases you need Xs (X11). For example, a demo project with barcodes requires System.Windows.Forms. And, if there are no special problems when starting the server on behalf of the user logged in via the GUI, then in cases when the project is launched via SSH, Apache or the Docker container will need to configure environment variables, and in the case of containers, it will also need to "forward" the X server from the outside.
The fifth point will consider the process of assembling connectors for some popular DBMSs. This is due to the fact that with FastReport (both Windows and Mono versions), plug-ins for using the DBMS are delivered in the form of source texts, and not ready-to-use libraries. Will have to collect manually.
But first things first. I assume that the system is already installed, and it is not completely empty - it has your favorite text editor and archiver.
Initial installation
If you believe the official manual, then the installation should not take much time; everything should go smoothly through apt. Well, let's get started. Install Mono, the XSP web server, the Apache web server, and the module that allows you to run ASP.Net applications through Apache.
apt-get install mono-complete mono-xsp apache2 libapache2-mod-monoNext, download and unpack the demo project. Hereafter, I will specifically use paths other than / var / www. First of all, this allows you to find errors in the configuration or even in the project itself. And secondly, the placement of third-party software products in / opt corresponds to the purpose of this directory.
mkdir –p /opt/fastreport/htdocs
# качаем
wget https://www.fastreport.ru/public_download/frmono_demo.zip -O /tmp/frmono_demo.zip
# распаковываем, копируем, запускаем
unzip /tmp/frmono_demo.zip –d /tmp/frmono.demo
cp –rp /tmp/frmono.demo/Demos/C#/Web/* /opt/fastreport/htdocs
cd /opt/fastreport/htdocs
xspFigure 1. Launch XSP
XSP - a lightweight web server for APS.Net, written in C # and allows you to quickly and easily test simple applications. If you believe the documentation and the advice of experienced - it is not recommended for use in a combat environment. By default, the XSP listens on port 9000 and all network adapters (IP 0.0.0.0). This procedure will show us whether in principle at least something works. I can assume that you will get some kind of exception. Alas, the authors of such a seemingly interesting tool for generating reports did not take care of the convenience of installing demonstration materials.
Fig. 2. A possible error message (the picture is clickable)
This problem is due to the fact that Mono cannot find the FastReport.Web.dll library. Moreover, the error occurs even if the file is copied to htdocs. I am not a specialist in .NET, and even more so in Mono. And I didn’t read the link to the post on the authors’ blog in the introduction right away (by the way, there is a question - why isn’t this emphasis, for example, file names are highlighted in bold instead of a directory?). According to this, I had to smash my head. The first possible solution is to copy the DLL to the current directory and set the environment variable MONO_PATH :
cp /tmp/frmono.demo/FastReport.*.dll ./
export MONO_PATH=./But here, too, failure awaits. Most likely, you received an exception that the namespace or type FastReport.Utils was not found. The problem can be solved - just register FastReport.Mono.dll in web.config.
Fig. 3. Compilation error - the Utils type or namespace was not found (the picture is clickable)
Add a dependency - in the web.config section, write the following line:
The version number and token may differ; at the moment, such are relevant. You can get a token from dll like this:
sn -T FastReport.Mono.dllCheck the version number as follows:
monodis --assembly FastReport.Mono.dll | grep "Version"The result of all our torment should be more or less sane display of the page with a demo report.
Fig. 4. Not quite working example
Alas, something went wrong. It was assumed that the browser window will have barcodes, as in the screenshot in the official FastReport.Mono manual. You may not have this error; I’ll tell you a bit about the reasons for its occurrence and the way to eliminate it.
In the meantime, back to the libraries. In the process of writing the instructions, another way was found to solve the problem with connecting FastReport.Web.dll and FastReport.Mono.dll (Figures 2 , 3), although, probably, .NET developers would have done that right away. It is enough to create the htdocs / bin directory and move FastReport.Web.dll and FastReport.Mono.dll there. There is no need to edit web.config and change MONO_PATH, Mono finds everything and throws no exceptions. Good or bad, it's hard to say. In principle, if everything is hidden behind the frontend in the face of Apache, then the directory with dlls can be hidden from prying eyes. The directory structure for this solution is shown in Figure 5.
Fig. 5. Demo project directory tree
Using System.Windows.Forms
The sample web report in the dependency list contains System.Windows.Forms. If you looked in web.config, then I think you paid attention to the line:
If you encounter the problem shown in screenshot 4 or in the console you see the message “No protocol specified”, then there is one of the following options:
- not installed or not running Xorg
- X server is running, you are trying to run XSP as root
- X server is running, you are trying to run XSP in ssh session
- X-server is running, you are using Apache, www-data user does not have the required rights
- Used by Docker
In the first case, you need to install / run X. Options 2 and 3 are essentially similar, and the problem is solved by setting environment variables DISPLAY , and possibly XAUTHORITY . The only difference is that if the OS was originally installed with a graphical environment, the user has the XAUTHORITY variable set and looks at the ~ / .Xauthority file, but the root does not. In principle, it is enough to do the following before starting XSP:
export DISPLAY=:0For root, you need to add:
export XAUTHORITY=/var/run/lightdm/root/:0Actually, running something on behalf of the superuser is a bad idea, but if you really want to ... In addition, setting the XAUTHORITY variable is still useful when configuring Apache to allow the www-data user to use the X server (relevant if during the installation of Debian graphic environment packages were selected). If the OS was initially installed in the minimum version, everything will be slightly different, because Xorg may very well be installed without a display manager. Or not installed at all.
If you are faced with the need to “wrap” FastReport.Mono in a container and decide to observe the principle of “1 service - 1 container”, you will have to create a container with an X server and “forward” the socket between the containers. You will have to use the Dummy display driver as a video driver. This configuration will be discussed in one of the following parts of the manual.
apt-get install xserver-xorg-video-dummyAn alternative option for Linux / Unix users may be to forward the X server from the host OS (tcp or unix socket). To get this feature on MacOS, you need to install XQuartz .
Configure Apache
In principle, setting up Apache 2.4 and mod_mono does not require any special tricks. If, suddenly, you did not follow my advice and installed the asp.net-examples package, I recommend that after testing the mod_mono functionality comment out the following line in
/etc/apache2/mods-available/mod_mono.conf:
Include /etc/mono-server4/mono-server4-hosts.confOtherwise, the alias / samples will be nailed to all your virtual hosts, by which the very examples of using ASP.Net will be opened. In addition, Apache can swear in logs and when restarted that mod_mono is already loaded. This is due to the fact that two modules are loaded - mod_mono and mod_mono_auto (for automatic deployment of applications). Mod_mono_auto can be safely disabled:
a2dismod mod_mono_auto && service apache2 restartThe virtual host configuration file from the official documentation is redundant in settings and in some places is not relevant. The minimum required configuration can be viewed under the spoiler.
001-mono.conf
Listen 8081
DocumentRoot "/opt/fastreport/htdocs"
MonoUnixSocket FrSite /tmp/.mod_mono_server
MonoServerPath FrSite /usr/bin/mod-mono-server4
# Если будем хранить библиотеки в директории htdocs/bin - последнюю часть пути можно опустить
# В противном случае надо оставить /opt/fastreport/htdocs или заменить на путь
# к каталогу с FastReport.*.dll
MonoPath FrSite /usr/lib/mono/4.5:/usr/lib:/usr/lib/mono/4.0:/opt/fastreport/htdocs
AddMonoApplications FrSite "/:/opt/fastreport/htdocs"
MonoAutoApplication Disabled
MonoDocumentRootDir /opt/fastreport/htdocs
MonoDebug false
MonoSetEnv FrSite DISPLAY=:0;HOME=/opt/fastreport
AddHandler mono .aspx .ascx .asax .ashx .config .cs .asmx .axd
Require all granted
Options Indexes FollowSymLinks MultiViews
AllowOverride All
SetHandler mono
MonoSetServerAlias FrSite
DirectoryIndex Default.aspx
# Если мы используем каталог bin для подключаемых dll
# В противном случае можно удалить
Require all denied
Actually, we put everything in /etc/apache2/sites-available/001-mono.conf using our favorite text editor, turn on the site and restart Apache:
a2ensite 001-mono && service apache2 restartParsing the entire config does not make deep sense, however, I would like to dwell on one line in more detail:
MonoSetEnv FrSite DISPLAY=:0;HOME=/opt/fastreportThis is a very noble crutch that allows you to solve 2 problems at once. I already described one of them in the section devoted to System.Windows.Forms- the application needs to specify DISPLAY. The second point is related to the fact that during the compilation and execution of the application, the directories ~ / .local and ~ / .mono are used, and the user www-data, which runs Apache, has his / her / home directory / var / www. I figured it’s not worth littering the entire system. In principle, it works. Of course, one could try changing the user and group for this particular virtual host, but it didn’t take off. As I understand it, mod_mono starts the server from an Apache user and when trying to use mpm_itk nothing worked, because The Apache process does not have access to the Monix server's UNIX socket. It is possible that the problem can be solved using FastCGI, but have not tried it, I do not pretend to be true.
The final touch is to give www-data user access to the X server. And here we can use the ability to install XAUTHORITY for superuser.
export XAUTHORITY=/var/run/lightdm/root/:0
export DISPLAY=:0
xhost + local:www-data
service apache2 restartI would like to draw attention to the fact that the changes made when xhost is called will be active only until the shutdown / reboot. If you use lightdm, then it makes sense to wrap this construct in a script and set it to autostart by adding the line display-setup-script = / path / to / script.sh in /etc/lightdm/lightdm.conf. Alternatively, you can change / etc / X11 / xinit / xinitrc.
Fig. 6. Workable example through Apache 2.4