Documentation Menu

Installation

Shows how to implement JavaScript logging in your ASP.NET Core web site.

• JSNLog works with both .NETStandard 2.0 or better, and .Net 4.5.2 or better.
• Simple well documented demo projects

1. Install JSNLog NuGet package

cd <web project directory>
dotnet add package JSNLog

2. Add JSNLog to the request pipeline

Call UseJSNLog in the Configure method in your Startup class, before any calls to UseStaticFiles or UseAuthorization.

using JSNLog;

public void Configure(...,
ILoggerFactory loggerFactory)
{
  ...
  // Add before UseStaticFiles
  app.UseJSNLog(loggerFactory);
  ...

This takes care of:

• Processing all log messages generated by JavaScript on the client. This is why UseJSNLog has to come before UseStaticFiles and UseAuthorization.
• Letting you configure JSNLog (how)
• For all HTML responses, inserting a script tag and some JavaScript code right before the closing </body> tag to add JSNLog on the page.

3. Done

Uncaught JavaScript exceptions will now be logged in your server side logs if your application targets netcoreapp3.0 or higher. Steps if your application targets netcoreapp2.0 or netcoreapp2.0

Next steps:

• Introduction to client side logging
• Configuration options

How to load jsnlog.js from an alternative url

UseJSNLog by default inserts a script tag that loads the jsnlog.js library from a CDN at:

https://cdnjs.cloudflare.com/ajax/libs/jsnlog/2.30.0/jsnlog.min.js

To load jsnlog.js from another location, configure the required location in the call to UseJSNLog:

public void Configure(..., ILoggerFactory loggerFactory)
{
  ...
  app.UseJSNLog(loggerFactory, new JsnlogConfiguration()
  {
    insertJsnlogInHtmlResponses = true,
    productionLibraryPath = "/lib/jsnlog/jsnlog.js"
  });
  ...

When and how to stop insertion of JSNLog in HTML responses

As you saw, UseJSNLog automatically inserts JSNLog in HTML responses by default. However, there are alternative ways to load JSNLog onto the page. You may want to use these for a number of reasons:

• JavaScript runs before page is loaded - UseJSNLog inserts JSNLog at the end of the page, just before the </body> tag. This means that if JavaScript is being executed while the page loads, JSNLog will not yet have been loaded and so any JavaScript exceptions will not be sent to the server.
• Need to load jsnlog.js from a module - UseJSNLog inserts a script tag to load the jsnlog.js library. You may want to load the jsnlog.js library as a module rather than via a script tag.
• Multiple instances of </body> on the page (unlikely) - UseJSNLog essentially watches the byte stream of the response and detects the first occurence of </body>. If for some reason the page contains the text "</body>" before the actual end of the body, it may insert JSNLog in the wrong place. Note that all user generated text should be HTML escaped, in which case user generated text would not cause this problem.
• </body> split over multiple buffers (unlikely) - UseJSNLog copies the response stream to the browser using a buffer. If the </body> tag is split over two buffers, it will fail to detect it and not insert JSNLog on the page.
• netcoreapp2.0 or netcoreapp2.1 - If your application uses one of these targets, it will use the netstandard2.0 version of JSNLog. This does not support automatically inserting JSNLog on HTML pages.

To stop automatic insertion of JSNLog in HTML responses, set the JsnlogConfiguration property insertJsnlogInHtmlResponses to false. Also set the productionLibraryPath property to ensure the script tag still gets generated:

public void Configure(..., ILoggerFactory loggerFactory)
{
  ...
  app.UseJSNLog(loggerFactory, new JsnlogConfiguration()
  {
    insertJsnlogInHtmlResponses = false,
    productionLibraryPath = "https://cdnjs.cloudflare.com/ajax/libs/jsnlog/2.30.0/jsnlog.min.js"
  });
  ...

If you do not use automatic insertion

Use tag helper to do the insertion

You will have to do the insertion yourself, using the jl-javascript-logger-definitions tag helper:

<jl-javascript-logger-definitions />

Because this simply generates script tags, you can use this in the head of the HTML page as well as the body.

Your _Layout.cshtml file would be a great place for this.

To ensure that your web site can use the jl-javascript-logger-definitions tag helper:

1. If your web site does not already have a _ViewImports.cshtml file, add an empty file with that name to your Views or Pages directory.
2. Add this line to your _ViewImports.cshtml file:

   @addTagHelper "*, jsnlog"

To load jsnlog.js as a module

• Set the productionLibraryPath property to null to prevent generation of the script tag:

  public void Configure(..., ILoggerFactory loggerFactory)
  {
    ...
    app.UseJSNLog(loggerFactory, new JsnlogConfiguration()
    {
      insertJsnlogInHtmlResponses = false,
                      productionLibraryPath = null
    });
    ...
  

• Options to load jsnlog.js as a module
• If you decide to load jsnlog.js as a module, your application is probably JavaScript centric.

  Out of the box, JSNLog does not need configuration beyond what is shown on this page. But you do have many configuration options, which can mostly be set both server side and client side (details).