Getting Started

Starting with v16.2.0.x, if you reference Syncfusion assemblies from trial setup or from the NuGet feed, you also have to include a license key in your projects. Please refer to this link to know about registering Syncfusion license key in your ASP.NET application to use our components.

This section describes how to configure the Syncfusion ASP.NET components into the ASP.NET applications. There are three ways for embedding our controls into ASP.NET application:

  1. Using Syncfusion Project Template
  2. Through Syncfusion NuGet Packages
  3. Through Manual Integration into the new/existing Application

The procedure that are followed in manual integration process is entirely automated when creating an application using Syncfusion Project template.

Using Syncfusion Project Template

Syncfusion provides the Visual Studio Project Template support for ASP.NET (EJWEB) components that will automatically include all the Syncfusion ASP.NET control’s client and server side dependencies are preconfigured and copied to the appropriate folders. The following steps help you to create the Syncfusion ASP.NET (Essential JS 1) application through the Visual Studio Project Template:

  1. To create a Syncfusion ASP.NET (Essential JS 1) project, follow either one of the options below:

    Option 1:
    Click Syncfusion Menu and choose Essential Studio for ASP.NET (Essential JS 1) > Create New Syncfusion Web Project… or Create New Syncfusion WebSite Project… in Visual Studio.

    NOTE

    In Visual Studio 2019, Syncfusion menu available under Extension in Visual Studio menu.

    Option 2:
    Choose File > New > Project and navigate to Syncfusion > Web > Syncfusion ASP.NET Web Application or Syncfusion ASP.NET Web Site in Visual Studio.

  2. Choose Templates > Visual C# > Syncfusion ASP.NET Web Site.
  3. Set a name and location for the project.
  4. Click OK to create the project.

    Then, Syncfusion licensing registration required message box will be shown as follow, if you are installed the trial setup or NuGet packages since Syncfusion introduced the licensing system from 2018 Volume 2 (v16.2.0.41) Essential Studio release. Please navigate to the help topic which is shown in the licensing message box to generate and register the Syncfusion license key to your project. Refer to this blog post for understanding the licensing changes introduced in Essential Studio.

Add your required controls in the ASPX Page. The code for adding DatePicker control within the “Default.aspx” file are as follows.

  • html
  • <ej:DatePicker ID="DatePicker" runat="server"></ej:DatePicker>
    • Another way of adding control into the Default.aspx page is by making use of the Toolbox option present in the Visual Studio. You need to just drag the required control from the toolbox and then drop it into the Content section of the Default.aspx page, and the required control code will automatically gets generated.

    • Finally build and run the project by pressing F5, so that you can now see the output similar to the following screenshot in your web browser.

    NOTE

    The Script Manager is mandatory in order to place our control initialization script in the page.

    Ensure whether the “ScriptManager” is added in the “Site.Master” or else add the “ScriptManager” to your web page.

    You just need to drag the “ScriptManager” from the toolbox under the “AJAX Extension” and then drop it into the Content section of the Default.aspx page, so that the required scripts to initiate our component will be added to your web page.

  • html
  • <asp:ScriptManager ID="ScriptManager1" runat="server">
         </asp:ScriptManager>

    NOTE

    Refer to the Embedded Resources section for more information on automatically loading script files from assemblies.

    NuGet Packages Structure

    The following structure is maintained for ASP.NET platform NuGet packages from 2015 Volume 2(v13.2.0.29). The latest package cannot be updated because of the installed Syncfusion NuGet packages prior version of 2015 Volume 2(V13.2.0.29). To update Syncfusion NuGet packages latest or above version of 2015 Volume 1 Service Pack-2(v13.1.0.30), uninstall the existing packages and install the following required package manually.

    Categories/Package Name
    Supported Controls
    Assemblies
    Assets
    Dependencies
    Scripts
    CSS

    Syncfusion.AspNet
    Grid
    Data Visualization
    Layout
    Editors
    Navigation
    Notification
    To know more information about the controls for above categories navigate to the following link.

    http://www.syncfusion.com/products/aspnet



    EJ.Web
    ej.webform.min.js

    -
    Syncfusion.Web.Base
    Syncfusion.Web.FileFormatsBase
    Syncfusion.AspNet.PdfViewer
    Pdf Viewer
    EJ.PdfViewer
    -
    -
    Syncfusion.AspNet
    Syncfusion.Web.FileFormatsBase
    Syncfusion.AspNet.ReportViewer
    Report Viewer
    Shared.WPF
    RichTextBoxAdv.WPF
    Chart.WPF
    GridCommon.WPF
    Grid.WPF
    SfMaps.WPF
    ReportControls.WPF
    ReportWriter.Base
    EJ.ReportViewer
    Gauge.WPF
    -
    -
    Syncfusion.AspNet
    Syncfusion.Web.Base
    Syncfusion.Web.FileFormatsBase
    Syncfusion.AspNet.FileFormats
    Excel
    Word
    PDF
    Power Point(Preview)
    DocToPDFConverter.Base
    ExcelToPDFConverter.Base
    PresentationToPDFConverter.Base
    HtmlConverter.Base
    OfficeChartToImageConverter.WPF
    ExcelChartToImageConverter.WPF
    SfChart.WPF
    Shared.WPF
    -
    -
    Syncfusion.Web.FileFormatsBase
    Syncfusion.AspNet.Pivot
    Pivot Grid
    Pivot Chart
    Pivot Client
    Pivot Gauge
    Olap.Base
    EJ.Pivot
    PivotAnalysis.Base
    ej.webform.min.js

    -
    Syncfusion.Web.Base
    Syncfusion.Web.FileFormatsBase
    Syncfusion.Web.Base
    -
    Linq.Base
    EJ
    EJ.Export
    -
    -
    Syncfusion.JavaScript
    Syncfusion.Web.FileFormatsBase
    -
    Compression.Base
    XlsIO.Base
    Pdf.Base
    DocIO.Base
    OfficeChart.Base
    Presentation.Base
    -
    -
    -

    Configure client side resources

    Configuring Syncfusion Bower Packages

    Overview

    Bower is a package manager for the Web. Syncfusion Bower package allows you to use the Syncfusion JavaScript Widgets in an efficient way.

    IMPORTANT

    Syncfusion JavaScript Bower package is available as public Git Repository and also registered as Syncfusion-JavaScript in the Bower registry.

    Bower Installation

    To configure the Bower in your machine you need to install node, npm and git. For more information about configuring the Bower package, please refer to the official site for bower.
    Syncfusion JavaScript Bower package can be configured in the following ways.

    1. Using command prompt

    2. Using bower.json file

    3. From local directory

    Using command prompt

    Perform the following steps to install Syncfusion Bower Package via command prompt in your web application.

    1. Open your web project’s location in a command prompt window.

    2. Then run the command Bower install .

      bower install syncfusion-javascript
      

    3. The Bower will install the Syncfusion JavaScript files into the project location to develop with Syncfusion controls.

    NOTE

    To install a particular version of a Bower package, you need to provide the version as suffix of the package name while installing. For example, run the following command to install the package of version 13.3.0.18.
    ‘bower install Syncfusion-javascript#13.3.0.18’

    Using bower.json file

    In another way, you can add the packages to the bower.json file by simply specifying the package name. This will install/restore the packages to your project. Please refer to the following image.

    NOTE

    ASP.NET 5 (preview) projects have bower.json file by default. If your project does not have bower.json file, run the following command from your project directory by Command prompt.
    ‘bower init’

    From local directory

    You can install the Syncfusion Bower package from a local directory. To perform this follow the below steps.

    1. Navigate to the Syncfusion JavaScript Bower repository location on GitHub and download the repository as zip by clicking the “Download ZIP” button, and extract the contents to any of the local directory in your computer.

    2. Then run the installed command by providing the package content’s location.

    Bower Update

    To update the installed Bower packages, run the command Bower update .

    bower update syncfusion-javascript
    

    Configuring Syncfusion npm Packages

    Overview

    The npm is the Package Manager for JavaScript. It makes easy for JavaScript developers to share and reuse the code, and also to update the code that you have shared.

    Syncfusion npm package

    Syncfusion JavaScript npm package is available in public Git Repository and also registered as syncfusion-javaScript in the npm registry.

    Syncfusion npm Installation

    To configure the npm, install the Nodejs and update the npm. For more information to configure the npm packages, refer to the official site of npm.

    syncfusion-javascript npm package can be configured in following ways.

    1. Using Command prompt

    2. Using package.json file

    3. From local directory

    Using command prompt

    Follow the below steps to install Syncfusion JavaScript npm package via command prompt in required web application location.

    1. Open project’s location in command prompt window.

    2. Run the installation command for npm.

      npm install syncfusion-javascript
      

    3. npm install the Syncfusion JavaScript assets into the project location to develop with Syncfusion controls.

    NOTE

    As per standard Syncfusion uses the 3 digit version for npm packages. To install a particular version of npm package, provide the version as suffix of the package name while installing.
    For example, run the following command to install Syncfusion JavaScript package of version 14.1.0.46.
    ‘npm install Syncfusion-javascript@14.1.46’

    Using package.json file

    Add the Syncfusion JavaScript packages to the package.json by simply specifying the package name. This will install/restore the package to the Visual Studio project. Refer to the following image.

    NOTE

    ASP.NET 5 (preview) projects have package.json file by default. Visual Studio project does not have package.json file, so run the following command using the project command prompt.
    ‘npm init’

    From Local Directory

    Install the Syncfusion JavaScript npm package from a local directory.

    1. Navigate to the Syncfusion JavaScript repository location on GitHub and download the repository as zip by clicking the “Download ZIP” button, and extract the contents to any of the local directory in your computer.

    2. Run the install command by providing the package content location.

    npm Update

    Updating global packages

    Run the following command to update the npm package globally.

    npm install g- syncfusion-javascript
    

    Updating local packages

    Run the following command to update the package by local location.

    npm update
    

    Configuring Syncfusion JSPM Packages

    Overview

    JSPM is a package manager for SystemJS universal module loader, built on top of the dynamic ES6 module loader. This can load any module format (ES6, AMD, CommonJS, and globals) directly from any registry such as npm and GitHub with flat versioned dependency management. Any custom registry endpoints can be created through the Registry API.

    Syncfusion JavaScript JSPM

    Syncfusion JavaScript JSPM package is available in public Git Repository and also registered as Syncfusion-JavaScript in the npm registry too.

    Syncfusion JSPM Installation

    Using Command prompt

    Follow the below steps to install Syncfusion JavaScript JSPM package via command prompt in required web application location.

    1. Open project’s location in command prompt window.

    2. A) To install the Syncfusion JavaScript JSPM package via GitHub repository.

      jspm install syncfusion=github:syncfusion/Javascript-Widgets
      

      B) To install the Syncfusion JavaScript JSPM package via npm repository.

      jspm install npm:syncfusion-javascript
      

    NOTE

    As per standard Syncfusion uses the 3 digit version for JSPM packages. To install a particular version of JSPM package, need to provide the version as suffix of the package name while installing.
    For example, run the following command to install Syncfusion JavaScript package of version 14.1.0.46.
    ‘JSPM install syncfusion=github:syncfusion/JavaScript-Widgets@14.1.46’

    JSPM Update

    Update all the installed packages by using following command.

    jspm update
    

    Update specific package by using following commands.

    jspm update npm:syncfusion-javascript
    

    (Or)

    jspm update syncfusion=github:syncfusion/JavaScript-Widgets
    

    Manual Integration of Syncfusion ASP.NET controls into the new/existing Application

    This topic mainly focuses on how to integrate the Syncfusion ASP.NET controls manually into the newly created/existing ASP.NET Web Forms application. Let’s look onto the procedure for making use of any of our ASP.NET controls within the ASP.NET Web application.

    Creation of First ASP.NET Web Application

    Follow the below steps to create a normal ASP.NET Web application

    1. Start the Visual Studio. Create a new Web Forms application by selecting File -> New -> Project and save it with a meaningful name as shown in the following.

    1. ASP.NET Web application is created successfully. Now you can build and run your application by pressing Ctrl+F5, it shows something similar to the following screenshot in your web browser.

    You have successfully created your first simple ASP.NET web application and now it is time to add some other essential things to your application that allows you to make use of our Syncfusion ASP.NET controls into it.

    For Existing Applications

    If you want to add our Syncfusion ASP.NET controls into your existing application, open your existing application and proceed with the following steps.

    Adding required CSS files

    To render the Syncfusion ASP.NET controls with its unique style and theme, it is necessary to refer to the required CSS files into your application. You need to copy all the required CSS files into your application from the following location.

    NOTE

    \Syncfusion\Essential Studio\17.1.0.38\JavaScript\assets\css\web For example, If you have installed the Essential Studio within C:\Program Files (x86), navigate to the following location. C:\Program Files (x86)\Syncfusion\Essential Studio\17.1.0.38\JavaScript\assets\css\web

    When you navigate to the above location, you can find the files shown in the following image that you need to copy entirely and paste it into your root application.

    Before pasting it into your application, create a folder structure with names ej/web within the Content folder of your application and place all the copied files into it as shown in the following.


    Solution Explorer - Project with CSS files copied into the Content folder

    NOTE

    The common-images folder is needed to be copied into your application mandatorily, as it includes all the common font icons and other images required for the control to render.

    Once the CSS files are added in your application, include the reference to “ej.web.all.min.css” file in the Site.Master page, within the head section.

  • html
  • <link href="Content/ej/web/default-theme/ej.web.all.min.css" rel="stylesheet" />

    Adding the required JavaScript files

    Adding the required JavaScript files into your application plays an important role, without which the Syncfusion controls cannot be created. It requires the following mandatory common script files.

    • jQuery (version supported from 1.7.1.min.js to latest jQuery version).
    • jquery.easing.1.3.min.js
    • jquery.globalize.min.js
    • jsrender.min.js

    Apart from the above common scripts, it is also necessary to refer to the ej.web.all.min.js file in your application that plays a major role in control creation. It also requires reference to the ej.webform.min.js file in your application, as it is responsible for the server-side event functionalities of the ASP.NET controls.

    The dependencies are available in the following locations of your machine. Please copy these files from the location given.

    Files Location
    jquery-3.3.1.min.js
    jsrender.min.js
    <Syncfusion Installed Location>\Essential Studio\17.1.0.38\JavaScript\assets\external
    ej.web.all.min.js <Syncfusion Installed Location>\Essential Studio\17.1.0.38\JavaScript\assets\scripts\web
    ej.webform.min.js <Syncfusion Installed Location>\Essential Studio\17.1.0.38\JavaScript\assets\scripts\common

    NOTE

    Example for “Syncfusion Installed location” is “C:\Program Files (x86)\Syncfusion”

    Now, create a folder named ej under the Scripts folder of your application and place the copied files ej.web.all.min.js and ej.webform.min.js into it as shown in the following.


    Solution Explorer - Script files copied into the Scripts folder of the project

    Once the scripts are added in your application, now it is necessary to include the reference to it in your application. This should be done within the Site.Master file, as we did previously for CSS files.
    Add the following script references in the Site.Master file within the head section.

  • html
  • <link href="Content/ej/web/default-theme/ej.web.all.min.css" rel="stylesheet" />
    <script src='<%= Page.ResolveClientUrl("~/Scripts/jquery-3.3.1.min.js")%>' type="text/javascript"></script>
    <script src='<%= Page.ResolveClientUrl("~/Scripts/jsrender.min.js")%>' type="text/javascript"></script>
    <script src='<%= Page.ResolveClientUrl("~/Scripts/ej/ej.web.all.min.js")%>' type="text/javascript"></script>
    <script src='<%= Page.ResolveClientUrl("~/Scripts/ej/ej.webform.min.js")%>' type="text/javascript"></script>

    NOTE

    As the above mentioned order, the script file of ej.webform.min.js should be referred at the last, that is whether we use individual script reference or ej.web.all.min.js script reference.

    If you want to refer to the CDN links instead of the direct script and CSS references in your application, you need to make use of the following references in the Site.Master file.

  • html
  • <head>
    
        <meta charset="utf-8" />
    
        <title><%: Page.Title %> - My ASP.NET Application</title>
    
        <link href="http://cdn.syncfusion.com/17.1.0.38/js/web/flat-azure/ej.web.all.min.css" rel="stylesheet" />
    
        <script src="http://cdn.syncfusion.com/js/assets/external/jquery-3.3.1.min.js"></script>
    
        <script src="http://cdn.syncfusion.com/js/assets/external/jquery.easing.1.3.min.js"></script>
    
        <script src="http://cdn.syncfusion.com/js/assets/external/jquery.globalize.min.js"></script>
    
        <script src="http://cdn.syncfusion.com/js/assets/external/jsrender.min.js"></script>
    
        <script src="http://cdn.syncfusion.com/17.1.0.38/js/web/ej.web.all.min.js"></script> 
    
        <script src="http://cdn.syncfusion.com/17.1.0.38/js/web/ej.webform.min.js"></script>
    
    </head>

    NOTE

    jQuery.easing external dependency has been removed from version 14.3.0.49 onwards. Kindly include this jQuery.easing dependency for versions lesser than 14.3.0.49 in order to support animation effects.

    Adding Syncfusion ASP.NET control

    Here, we will see how to add the DatePicker control into the newly created Syncfusion ASP.NET Web Application. To add the control, we can use either of the following two ways:

    • Drag and drop the control from the toolbox.
    • Manually using the control code.

    Drag and drop the control from the toolbox

    1. An easy way of adding control into the Default.aspx page is by making use of the Toolbox option present in the Visual Studio. When you install Essential Studio Package or ASP.NET setup in your machine, all the available ASP.NET controls are automatically configured into the Visual Studio Toolbox.

    You just need to drag the required control from the toolbox and then drop it into the Content section of the Default.aspx page, so that the required control code gets generated automatically and also the required dependent assembly get registered automatically.


    Toolbox

    1. When you drag and drop the DatePicker control into the Default.aspx page, the page looks as the image shown in the following with the automatic control code generated and the required assemblies registered.


    Default.aspx page with DatePicker control code and assembly registered for it at the top

    Manually using the control code

    If you want to add the control code manually, follow the below steps.

    Assembly Reference

    Refer to the following assemblies in your newly created ASP.NET application that allows you to use any of the Syncfusion ASP.NET controls within it.

    • Syncfusion.EJ
    • Syncfusion.EJ.Web

    The reference to the Syncfusion assemblies can be added to your application in either of the following ways.

    • Referring from GAC
    • Referring from the installed location
    Referring from GAC
    1. Once you have installed the Essential Studio package in your system, the Syncfusion assemblies are automatically registered in the GAC. You can easily add the reference assemblies to your project by choosing Add Reference option as shown in the following.


    Right click on the References –> choose Add Reference option

    1. Now the Reference Manager pop-up will appear on the screen. In that pop-up, select the required assemblies from the Extensions tab as follows, by choosing the appropriate versions (13.1450.0.21). The version to be chosen for the reference assemblies is based on the Framework used in the application.


    Reference Manager Pop-up

    Referring from the installed location
    1. Add the reference assemblies to your project by choosing Add Reference option as shown in the following.


    Right click on the References –> choose Add Reference option

    1. Now the Reference Manager pop-up will appear on the screen. Select the Browse tab in it and navigate to the installed location of the Syncfusion Essential Studio package in your system. (As illustrated in the following image.)

    NOTE

    \Syncfusion\Essential Studio\17.1.0.38\precompiledassemblies\17.1.0.38

    NOTE

    For example, If you have installed the Essential Studio package within C:\Program Files (x86), navigate to the following location.

    NOTE

    C:\Program Files (x86)\Syncfusion\Essential Studio\17.1.0.38\precompiledassemblies\17.1.0.38


    Reference Manager Pop-up with Browse button clicked

    NOTE

    In the above image, the folders 3.5, 4.0, 4.5, 4.5.1 denotes the .NET Framework version. Based on the Framework version used in your application, you can choose assemblies from the appropriate folders. The Syncfusion.EJ.Web and other assemblies like Syncfusion.EJ are available within these folders.

    1. Add the Syncfusion.EJ and Syncfusion.EJ.Web assemblies to your application from the following specified location.

    NOTE

    \Syncfusion\Essential Studio\17.1.0.38\precompiledassemblies\17.1.0.38\4.5
    For example, If you have installed the Essential Studio package within C:\Program Files (x86), navigate to the following location.
    C:\Program Files (x86)\Syncfusion\Essential Studio\17.1.0.38\precompiledassemblies\17.1.0.38\4.5


    Reference Manager Pop-up with assemblies selected

    1. Once the assembly selection is done, click OK to add the selected references to your project. You can view the assembly references added to your application, in the solution explorer as shown in the following.


    Selected Assemblies added to the Project reference

    NOTE

    We have removed dependency for Syncfusion.Core assembly since v13.2.0.29. If you are using the latest version, this assembly is not required in your application. Refer to this KB document for more details.

    Registering Syncfusion Assemblies within the Web.config

    In your application’s web.config file, add the following assembly information within the tag.

  • xml
  • <system.web>
        <compilation debug="true" targetFramework="4.5">
              <assemblies>
    
                <add assembly="Syncfusion.EJ, Version=16.3450.0.21, Culture=neutral, PublicKeyToken=3d67ed1f87d44c89" />
    
                <add assembly="Syncfusion.EJ.Web, Version=16.3450.0.21, Culture=neutral, PublicKeyToken=3d67ed1f87d44c89" />
    
              </assemblies>
        </compilation>
        <authentication mode="Forms"></system.web>
    1. Add the following DatePicker code within the Default.aspx file, as shown in the image following it.
  • html
  • <ej:DatePicker ID="DatePicker" runat="server"></ej:DatePicker>

    NOTE

    Add the DatePicker code within the Content section, by removing the unwanted code within it.

    1. Also register the required assemblies within the Default.aspx page at the top where you are using the control as shown in the following.

    1. Finally build and run the project by pressing F5, so that you can now see the output similar to the following screenshot in your web browser.


    DatePicker control displaying on the web browser

    Thus the DatePicker control is rendered successfully with its default appearance. You can then use its various properties to set its value and also make use of its available events to trigger when necessary.

    NOTE

    The Script Manager is mandatory in order to place our control initialization script in the page.

    Ensure whether the “ScriptManager” is added in the “Site.Master” or else add the “ScriptManager” to your web page.

    You just need to drag the “ScriptManager” from the toolbox under the “AJAX Extension” and then drop it into the Content section of the Default.aspx page, so that the required scripts to initiate our component will be added to your web page.

  • html
  • <asp:ScriptManager ID="ScriptManager1" runat="server"> 
         </asp:ScriptManager>