DotNetClientSample

Overview

This SDK uses a C# class library that can be used to send requests to an eBillingHub Data Services API from a server-side event for an ASP.NET page or from a .NET Windows application.

Prerequisites

Installation

Download the SDK

Download the sample and then unzip the downloaded file. The SDK includes the following projects:
Configure the SDK

details....

SDK members

Using the SDK

Add references to the SDK libraries

Add a references for the following libraries to web site's project:
- Ebh.Samples.SDK
Sample page for calling API methods without parameters

Add a new ASP.NET web page to your site. details....

Note that this example assumes that the new web page uses a master page to provide textboxes for the user's credentials.

The ASP.NET page could look something like the following:
```
<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPages/InvoiceSearch.Master"
    AutoEventWireup="true" CodeBehind="GetAllInvoices.aspx.cs"
    Inherits="Ebh.Samples.WebApplication.GetAllInvoices" %>
<%@ MasterType virtualPath="~/MasterPages/InvoiceSearch.Master"%>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>

<asp:Content ID="Content2" ContentPlaceHolderID="cphSearchType" runat="server">
    <h3>Get all invoices</h3>
</asp:Content>

<asp:Content ID="Content3" ContentPlaceHolderID="cphSearchOptions" runat="server">
    <p>
        <asp:Button ID="btnSearch" Text="Submit search" runat="server" OnClick="btnSearch_Click" />
    </p>
</asp:Content>
```
Edit the code-behind file for your new web page

First, add using or Imports statements for each of the SDK libraries:
```
using Ebh.Samples.SDK;
```
To use an EBH Data Services API, instantiate one of the API objects and then call one of its methods. For logic requiring multiple calls to the method or calls to multiple methods, the API object can be instantiated once and then reused for all of the calls. For example, this code instantes an object for the Invoices API and then calls a method that retrieves data for all of the firm's invoices:
```
InvoicesApi api = new InvoicesApi(Master.BaseUrl, Master.UserName, Master.Password, ResponseFormats.Json, Encoding.Default);
ApiResponse apiResponse = api.GetAll();
```
All of the API methods return an ApiResponse object that contains the HTTP status code (e.g. 200 OK, 404 Not Found, etc) plus either the JSON or XML data for the API type (e.g. invoice data) or an error message. Here is an example that copies the response data to a text box on the page. For this example, the code will be placed into the code-behind file for the master page to simplify calling the API from multiple pages.
```
if (apiResponse.StatusCode == System.Net.HttpStatusCode.OK)
    txtResults.Text = apiResponse.Data;
else
    txtResults.Text = String.Format("Error: {0}: {1}", apiResponse.StatusCode, apiResponse.StatusDescription);
```
Continuing the example for creating a web page, edit the page's code-behind file to add the server-side event handler for the Search button. This code will instantiate one of the API objects (InvoicesAPI in this example), call one of the API's methods and then handle the results. Remember that this example assumes that the page uses a master page that provides textboxes for obtaining the user's credentials.

This sample code snippet calls the GetAll method of the Invoices API to get data about all of the firm's invoices. If the API call is successful, the page displays the response data (JSON in this example) on the page. If the API call fails, the page displays details about the error.
```
protected void btnSearch_Click(object sender, EventArgs e)
{
    InvoicesApi api = new InvoicesApi(Master.BaseUrl, Master.UserName, Master.Password, ResponseFormats.Json, Encoding.Default);
    ApiResponse apiResponse = api.GetAll();
    Master.HandleSearchResults(apiResponse);
}
```

Sample page for calling API methods that require parameters

Add a new ASP.NET web page to your site. details....

This page is very similar to the page in the previous example, except it has controls for obtaining search criteria from the user. Refer to the previous example for information on how to use the API.

The ASP.NET page could look something like the following:

<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPages/InvoiceSearch.Master"
    AutoEventWireup="true" CodeBehind="GetInvoicesByInvoiceId.aspx.cs"
    Inherits="Ebh.Samples.WebApplication.GetInvoicesByInvoiceId" %>
<%@ MasterType virtualPath="~/MasterPages/InvoiceSearch.Master"%>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>

<asp:Content ID="Content2" ContentPlaceHolderID="cphSearchType" runat="server">
    <h3>Get all invoices</h3>
</asp:Content>

<asp:Content ID="Content3" ContentPlaceHolderID="cphSearchOptions" runat="server">
    <p>
        Invoice ID: <asp:TextBox ID="txtInvoiceId" runat="server" />
    </p>
    <p>
        <asp:Button ID="btnSearch" Text="Submit search" runat="server" OnClick="btnSearch_Click" />
    </p>
</asp:Content>

Edit the code-behind file for your new web page

The process and logic for this file is very similar to the page in previous example, except that search criteria parameters must be passed to the API's methods. This example uses the GetByInvoiceId method for the Invoices API to find an invoice using the firm's invoice ID.

protected void btnSearch_Click(object sender, EventArgs e)
{
    InvoicesApi api = new InvoicesApi(Master.BaseUrl, Master.UserName, Master.Password, ResponseFormats.Json, Encoding.Default);
    ApiResponse apiResponse = api.GetByInvoiceId(txtInvoiceId.Text);
    Master.HandleSearchResults(apiResponse);
}

Complete Example

Here are listings of all of the files for the previous examples.

Web.config

TODO: add web.config sample

InvoiceSearch.Master

<%@ Master Language="C#" AutoEventWireup="true"
    CodeBehind="InvoiceSearch.master.cs"
    Inherits="Ebh.Samples.WebApplication.MasterPages.InvoiceSearch" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
    <asp:ContentPlaceHolder ID="head" runat="server">
    </asp:ContentPlaceHolder>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <asp:ContentPlaceHolder ID="cphSearchType" runat="server">

        </asp:ContentPlaceHolder>

        <p>
            Username:
            <asp:TextBox ID="txtUsername" runat="server" />
        </p>
        <p>
            Password:
            <asp:TextBox ID="txtPassword" runat="server" TextMode="Password" />
        </p>

        <asp:ContentPlaceHolder ID="cphSearchOptions" runat="server">
        
        </asp:ContentPlaceHolder>

        <asp:Literal ID="litResults" runat="server" EnableViewState="false" Mode="Encode" Visible="false" />

    </div>
    </form>
</body>
</html>

InvoiceSearch.Master.cs

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Configuration;

using Ebh.Samples.SDK;

namespace Ebh.Samples.WebApplication.MasterPages
{
    public partial class InvoiceSearch : System.Web.UI.MasterPage
    {

        public string BaseUrl
        {
            get
            {
                string value = ConfigurationManager.AppSettings["EbhReportingBaseUrl"];
                if (String.IsNullOrEmpty(value))
                    throw new ConfigurationErrorsException("EbhReportingBaseUrl must be defined in appSettings in web.config");
                return value;
            }
        }

        public string UserName
        {
            get { return txtUsername.Text; }
        }

        public string Password
        {
            get { return txtPassword.Text; }
        }

        public void HandleSearchResults(ApiResponse apiResponse)
        {
            if (apiResponse.StatusCode == System.Net.HttpStatusCode.OK)
                litResults.Text = apiResponse.Data;
            else
                litResults.Text = String.Format("Error: {0}: {1}", apiResponse.StatusCode, apiResponse.StatusDescription);
            litResults.Visible = true;
        }

        protected void Page_Load(object sender, EventArgs e)
        {
            txtUsername.Focus();
        }

    }
}

GetAllInvoices.aspx

<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPages/InvoiceSearch.Master"
    AutoEventWireup="true" CodeBehind="GetAllInvoices.aspx.cs"
    Inherits="Ebh.Samples.WebApplication.GetAllInvoices" %>
<%@ MasterType virtualPath="~/MasterPages/InvoiceSearch.Master"%>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>

<asp:Content ID="Content2" ContentPlaceHolderID="cphSearchType" runat="server">
    <h3>Get all invoices</h3>
</asp:Content>

<asp:Content ID="Content3" ContentPlaceHolderID="cphSearchOptions" runat="server">
    <p>
        <asp:Button ID="btnSearch" Text="Submit search" runat="server" OnClick="btnSearch_Click" />
    </p>
</asp:Content>

GetAllInvoices.aspx.cs

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Text;

using Ebh.Samples.SDK;

namespace Ebh.Samples.WebApplication
{
    public partial class GetAllInvoices : System.Web.UI.Page
    {

        protected void btnSearch_Click(object sender, EventArgs e)
        {
            InvoicesApi api = new InvoicesApi(Master.BaseUrl, Master.UserName, Master.Password, ResponseFormats.Json, Encoding.Default);
            ApiResponse apiResponse = api.GetAll();
            Master.HandleSearchResults(apiResponse);
        }

    }
}

GetInvoicesByInvoiceId.aspx

<%@ Page Title="" Language="C#" MasterPageFile="~/MasterPages/InvoiceSearch.Master"
    AutoEventWireup="true" CodeBehind="GetInvoicesByInvoiceId.aspx.cs"
    Inherits="Ebh.Samples.WebApplication.GetInvoicesByInvoiceId" %>
<%@ MasterType virtualPath="~/MasterPages/InvoiceSearch.Master"%>

<asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
</asp:Content>

<asp:Content ID="Content2" ContentPlaceHolderID="cphSearchType" runat="server">
    <h3>Get all invoices</h3>
</asp:Content>

<asp:Content ID="Content3" ContentPlaceHolderID="cphSearchOptions" runat="server">
    <p>
        Invoice ID: <asp:TextBox ID="txtInvoiceId" runat="server" />
    </p>
    <p>
        <asp:Button ID="btnSearch" Text="Submit search" runat="server" OnClick="btnSearch_Click" />
    </p>
</asp:Content>

GetInvoicesByInvoiceId.aspx.cs

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Text;

using Ebh.Samples.SDK;

namespace Ebh.Samples.WebApplication
{
    public partial class GetInvoicesByInvoiceId : System.Web.UI.Page
    {

        protected void btnSearch_Click(object sender, EventArgs e)
        {
            InvoicesApi api = new InvoicesApi(Master.BaseUrl, Master.UserName, Master.Password, ResponseFormats.Json, Encoding.Default);
            ApiResponse apiResponse = api.GetByInvoiceId(txtInvoiceId.Text);
            Master.HandleSearchResults(apiResponse);
        }

    }
}

Overview

Prerequisites

Installation

Download the SDK

Configure the SDK

SDK members

Using the SDK

Add references to the SDK libraries

Sample page for calling API methods without parameters

Edit the code-behind file for your new web page

Sample page for calling API methods that require parameters

Edit the code-behind file for your new web page

Complete Example

Web.config

InvoiceSearch.Master

InvoiceSearch.Master.cs

GetAllInvoices.aspx

GetAllInvoices.aspx.cs

GetInvoicesByInvoiceId.aspx

GetInvoicesByInvoiceId.aspx.cs