# Introduction to the .NET API

The Exago interface consists of two elements: The User Interface and the API. The User Interface is built directly onto the .NET API. This means that .NET applications can interface directly with Exago. Non-.NET applications can interface with the SOAP Web Service API or the REST Web Service API, which offer subsets of the .NET API.

This guide will walk through the process of integrating Exago into a .NET-based web application. We will demonstrate how to use the API to connect with an existing installation of the Exago Application, and showcase how to do some basic report management tasks. For a full list of classes see the Technical Guide.

For this example, we will load an existing report, modify its run-time filters, and then execute the report in a browser window.

# Referencing the Api

First reference the Web Reports API library. This is usually located in your Installation Directory > bin folder, and is called WebReportsApi.dll. This library contains all the namespaces necessary to utilize the Web Application's features.

Include the following namespaces for now:

- WebReports.Api: Contains the Api class which is the main interaction class between Exago and your application.
- WebReports.Api.Reports: Contains the Report class, for creating and managing reports.
- WebReports.Api.Roles: Contains classes for managing role security settings.

# Creating an Api Object

An Api Object is the main class you need to create in order to interact with Exago. It contains the first and last points of entry for each instance of your application.

Create an Api Object using the following overloaded constructor:

    Api myApi = new Api(AppPath);

AppPath is the physical or virtual location of your Exago installation.

> NOTE: You can use the ConfigFile parameter to load an Exago Config file. If left out, it will default to WebReports.xml.

> NOTE: Do not call the constructor method with empty parameters.

# Loading a Report

Now let's load the report we want to modify.

    Report myReport = (Report)myApi.ReportObjectFactory.LoadFromRepository(@"TestReport");

> NOTE: You do not need to specify the file extension. The application will not allow reports of the same name but different types.

The ReportObjectFactory class is the collection class for report management methods. This contains methods for creating, loading, copying, saving, renaming, and deleting report files. It can be used to work within a repository or a temporary browser session, or both if necessary. In this case, we're simply loading a pre-existing report into the Api.

> NOTE: Several methods reference an Active report by default. This is usually the last report accessed, but can be specified by the Active property of the ReportObjectFactory.

Reports called from within the ReportObjectFactory are ReportObject objects, which is a general class representing the various report types.

We are casting the ReportObject called from the factory to a Report, because we know it is a report. Report inherits several methods from ReportObject, but greatly expands the management capabilities.

> Note: If we loaded a dashboard report or a chained report, we would cast it to DashboardReport or ChainedReport respectively.

See Loading Reports in the .NET API for more information.

# Retrieving the Role Security

Let's see if the current user has access to the database object we want to filter for.

    if (myApi.Roles.ActiveRole.Security.DataObjects.GetDataObject("Customers") != null)

    { Permission Granted!; }

    else Permission Denied!;

The Roles object allows for accessing and modifying the elements found within the Admin Console. Changing or adding Role settings will only persist for the current session, and will not modify the config file.

We can also set some additional security and restrict the user from seeing specific data object rows:

    DataObjectRow dataObjectRow = myApi.Roles.ActiveRole.Security.DataObjectRows.NewDataObjectRow();
    dataObjectRow.ObjectName = "SSN";
    dataObjectRow.FilterString = "false";

# Modifying the Report

Now that we have loaded and declared our Report object, we can begin to modify its contents. Let's clear out the pre-existing runtime filters, and add one of our own:

    foreach (Filter oldFilter in myReport.Filters)
     { myReport.Filters.Remove(oldFilter); }

    Filter myFilter = myReport.Filters.NewFilter();
    myFilter.DbName = "Customers.CompanyName";
    myFilter.Operator = wrFilterOperator.NotEqualTo;
    myFilter.Value = "Exago Inc.";
    myFilter.AndOrWithNext = wrFilterAndOrWithNext.And;

Note that all these modifications will take place within the current session, and will not modify the report data unless you specifically overwrite the report file.

# Closing the Session and Executing

That's enough for now; Let's execute the altered report. First, some administrative stuff.

Set the report execute type to HTML, so it runs in the browser:

    myReport.ExportType = wrExportType.Html;

And hide the application tabs to avoid clutter:

    myApi.ShowTabs = false;

Now save the changes we've made to the Api. This will load the report into a temporary space in the Api to prepare for execution.

    myApi.ReportObjectFactory.SaveToApi(myReport);

And we're all set! Calling the following method will end the session, performing the specified action, and return the session URL. The session URL is an alphanumeric single-use identifier for the session. Append it to your Exago application URL.

Since we loaded a report into the Api, the action defaults to Execute.

    string url = @"//MyDomainServer/Exago/" + myApi.GetUrlParamString(ExagoHome);

> The ExagoHome parameter can be used to specify the Exago application's home page. It will default to ExagoHome.aspx.

Now redirect your browser to the generated URL and see the results!