Report Server for .NET Documentation

[ighristov]

Tasks

Preview Give feedback

1. Layout (sync with Yordan Mitev) - another root node, section, etc. #1394
   +0
   
2. API for RS.NET #1396
   +0
3. Documentation page for the logging functionality (SeriLog) #1478
   +0
   

[ighristov]

This is a draft for the initial release of RS.NET docs. Please edit them as you wish.

RS.NET is in PREVIEW mode and this documentation is a subject of change. The documentation for RS.NET reflects the latest released version of our product.

Installation on Windows

1) Installation Process

[MSI screenshot].

• RS.NET is currently distributed along with RS for .NET FW 4.6.2.
• Installation of RS for .NET Framework (old RS) has no changes.
• By default the installer does not install RS.NET. Users must click Customize to install RS.NET.
• In order to host ASP.NET web apps on IIS, the ASP.NET Core Hosting Bundle must be installed. https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/?view=aspnetcore-8.0
  MSI will show a warning in case the module is not installed. The user will be able to continue the installation although the module was not found.
  Known issue: the detection returns false negative result on machines having Windows 11, Windows Server 2016 and Windows Server 2022. This is fixed and will be included in our next release.
• The installer will configure the ports for installing the RS.NET and RS.NET Server Agent, taking the available ports from 80 upwards [screenshot]

2) Installed Assets

• RS.NET is installed in {Installation Folder}\Telerik Report Server\Telerik.ReportServer.Web.NET. Cross-platform distribution of RS.NET is in the '_non-windows' subfolder.
• RSA.NET is installed in {Installation Folder}\Telerik Report Server\Services.NET. Cross-platform distribution of RSA.NET is in the '_non-windows' subfolder.

3) Automatic Configuration

MSI will do the initial configuration of RS.NET and RSA.NET on Windows, making them ready-to-run.
For configuring RS.NET and RSA.NET on non-windows platforms please check this article (link to other article with linux/docker docs)

4) Troubleshooting

• ANCM module - brief explanation what is, why it's needed, and why the MSI shows warning on Windows 11, Windows Server 2016 and 2022.
• No RS.NET assets installed - Mitko said it happened on his end, I have no idea why.
• No Default Service Agent installed:
  • this can be checked in RS Configuration page -> ServiceAgent. If the install was successful, there should be one entry named "DefaultServiceAgent" with the URL shown on the last page of the MSI wizard.
  • if there's no DefaultServiceAgent, then the Service Agent was not initialized successfully.
• Logging(Log creation and redirection) - Enable stdout and stderr console output to disk and diagnostics logs(web.config):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\Telerik.ReportServer.Web.Core.dll" stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" >
            <handlerSettings>
              <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
              <handlerSetting name="debugLevel" value="FILE,TRACE" />
            </handlerSettings>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

• Event Viewer logs - Application Event Log (IIS)

Initialization process (not sure where this should be!) (Manual Configuration)

1. When the server is started and passes the ConfigureStorage and Register Administrator pages, it stores those settings in a file named ReportServerAdmin.json.
2. THen RS checks its appsettings.json for the key "InitialAgentUrl". If the installation has passed successfully, the key must exist and must have a valid value like "http://localhost:84". This is where the MSI has registered the RSA app.
3. The RS calls this URL and passes the storage settings to the agent. The storage settings for the agent will be saved in a file in the Agent's directory, named \Services.NET\ServiceAgent.json. If such a file does not exist, the agent was not initialized or registered in IIS.

Reset procedure:

1. Delete the file \Services.NET\ServiceAgent.json from Agent's folder;
2. CHeck if RSA works, by calling "http://localhost:84/api/system/isalive" from browser (where localhost:84 is the URL of TSA). If the agent is working, the result must be HTTP ERROR 401 - Unauthorized. If the agent is not working, the result should be 404 - Not Found.
3. Open RS's appsettings.json and add/edit the key "InitialAgentUrl": "http://localhost:84".
4. Restart the RS and RSA.
5. Check the RS' COnfiguration -> ServiceAgent page. THe entry "DefaultServiceAgent" with the url http://localhost:84 should now be present.
6. To check the TSA, ensure the Mail Server settings in Configuration page are valid.