Developers »
Web Services » Here
Web Services Tutorial with .NET
Last revision: 2007-09-19
Target audience: developers, system administrators
In this tutorial, we will see how to use Lokad Web Services in a simple Console Application written in C#. Lokad specializes in business time-series forecasting, but this document is neither an introduction to Lokad nor an introduction to Web Services.
Download: source-code for this tutorialRequirements
- A Lokad account (*) (registration is free).
- C# and .Net: intermediate level (read a C# intro).
- Web Services: limited knowledge (read a WS intro).
(*) We suggest to use the
sandbox because its usage is free for development purposes.
Introduction
Web Services are an industrial-strength standard currently embraced by most (if not all) major software vendors. Lokad features Web Services: all the operations that can be performed from the web application can also be performed programmatically through our Web Services. The Lokad Web Services can be reached at
In this tutorial, we will see how to use Lokad Web Services in a simple Console Application written in C#. First, we will see how proxy classes can be generated thanks to
wsdl.exe. Then we will examine how to use those classes to perform the typical Lokad operation life-cycle: upload data and retrieve forecasts.
Project setup with wsdl.exe
wsdl.exe (Web Services Description Language Tool) is a very convenient tool provided with the .NET Framework SDK for consuming Web Services. From a high level point of view,
wsdl.exe retrieves the XML description of the Web Services and generates a proxy implementation in C# that can be included in a .NET project.
The syntax required to generate a
Lokad.cs proxy implementation for the Lokad Web Services is
wsdl.exe /l:cs /namespace:Lokad.WebServices /out:Lokad.cs http://ws.lokad.com/TimeSeries.asmx?wsdl
(please note that there is no line break, it's a single command)
For the sake of clarity, let's review the arguments provided to
wsdl.exe.
/l:cs indicates that the generated file will be in C#./namespace:Lokad.WebServices indicates the namespace that will contain the generated code./out:Lokad.cs defines the output file where the code should be written.- The URL specifies the Web Services to be proxied.
]
Let's now create a new console application from Visual Studio 2005. Go to File » New » Project and choose Console Application. In the newly created project, add the Lokad.cs file that you've just generated with
wsdl.exe. Finally, right-click on the project References and select Add Reference... » .Net » System.Web.Services to be added as a reference to your project. Your project should now compile.
Web Services Authentication
Lokad Web Services are authenticated, which means that you have to provide the username and password associated with your Lokad Web Account to access our Web Services. Technically, Lokad relies on SOAP headers to authenticate a Web Method call. The code provided below illustrates how you can check that your call is correctly authenticated.
using Lokad.WebServices;
...
string username = "email@example.com";
string password = "mypassword";
AuthHeader authentication = new AuthHeader();
authentication.UserName = username;
authentication.Password = password;
TimeSeries timeSeries = new TimeSeries();
Console.WriteLine("Is authenticated: {0}",
timeSeries.IsAuthenticated());
Console.WriteLine("Adding username/password.");
timeSeries.AuthHeaderValue = authentication;
Console.WriteLine("Is authenticated: {0}",
timeSeries.IsAuthenticated());As you may already have noticed,
AuthHeader and
TimeSeries are part of the
Lokad.WebServices namespace. Those types have been generated by
wsdl.exe. The
TimeSeries class is a proxy implementation that let you seamlessly access Lokad Web Services in a typical C# manner. The expected console output for the above code sample is:
Is authenticated: False
Adding username/password.
Is authenticated: True
Time-series management
Lokad specializes in time-series forecasting. Before actually performing a forecast, you first need to upload your data; and this can be easily achieved with our Web Services. Technically, a time-series is simply a named array of time-value pairs. Let's see how a time-series can be generated programmatically.
static TimeSerie GetSampleTimeSerie()
{
int timeSerieLength = 10;
TimeSerie serie = new TimeSerie();
serie.Name = "MySampleTimeSerie";
serie.UtcOffset = +1.0;
serie.TimeValues = new TimeValue[timeSerieLength];
for (int i = 0; i < serie.TimeValues.Length; i++ )
{
TimeValue timeValue = new TimeValue();
timeValue.Time = DateTime.Now.AddDays(i);
timeValue.Value = random.NextDouble();
timeValue.Time = DateTime.SpecifyKind(
timeValue.Time, DateTimeKind.Unspecified);
serie.TimeValues[i] = timeValue;
}
return serie;
}The static method
GetSampleTimeSerie() creates a time-series named
MySampleTimeSerie. Note that we specify first a
UtcOffset in the example above; this value is expressed in hours according to the formula
local time = UTC time + offset. Then, we set the
DateTimeKind to
Unspecified. This pattern is used to avoid implicit offset shifting when
DateTime values get serialized and then deserialized by the
SoapFormatter.
Once the time-series is defined, 10 time-value pairs are added. In our sample, for simplicity, the values are regularly spaced (one day increment for each value) but this is not a requirement. The intervals between the successive values can vary arbitrarily.
Tip: you can programmatically retrieve the UTC offset (see MSDN for further information on the
TimeZone class) based on the local machine settings with:
serie.UtcOffset =
TimeZone.CurrentTimeZone.GetUtcOffset(DateTime.Now).Hours;Naming conventions:although the word serie (singular) does not exist in English, we have found it quite convenient to distinguish in source code serie (singular) from series (plural). So, when the term serie is used in our examples, it's not a mistake, it's on purpose.
The
GetSampleTimeSerie() method provides a time-series instance. Lets add this time-series to your Lokad account.
TimeSerie timeSerie = GetSampleTimeSerie();
timeSeries.AddSerie(timeSerie);
// timeSeries.DeleteSerie(timeSerie.Name);
To delete a time-series from your account, you just need to specify the name identifier of the time-series in question. You can also retrieve the names of the existing time-series in your account; the following snippet prints to the console the names of the time-series in your account.
foreach (string serieName in timeSeries.GetAllSerieNames())
{
Console.WriteLine("Series name: {0}", serieName);
}Forecasting task management
Before you can retrieve a time-series forecast, you need to define a forecasting task that will specify how the forecasted time-series should be computed. In the Lokad data model, a forecasting task is always associated with a particular time-series; several forecasting tasks can be associated with the same time-series.
static Task GetSampleTask()
{
Task task = new Task();
task.Name = "MySampleTask";
task.Aggregator = Aggregator.Sum;
task.Period = Period.Day;
task.FuturePeriods = 3;
return task;
}Tip: the time-series names should be unique within the scope of your Lokad account (you cannot have two distinct time-series identified by the same name). However, the names of the forecasting tasks only need to be unique within the scope of their base time-series. In other words, you can have several forecasting tasks identified by the same name but associated with different time-series.
You can use the TimeSeries class to add the newly created Task instance to your Lokad account.
TimeSeries timeSeries = new TimeSeries();
timeSeries.AuthHeaderValue = authentication;
Task task = GetSampleTask();
timeSeries.AddTask(timeSerie.Name, task);
Retrieving forecasts
To retrieve your forecasts through our Web Services, you need to activate the Enterprise subscription plan in your Lokad account. Note that you won't be charged upfront, but only at the end of each 30-day period (if you decide to continue with your subscription). Time-series forecasts can be retrieved using the
TimeSeries class.
foreach (TimeValue timeValue in
timeSeries.GetForecast(timeSerie.Name, task.Name))
{
Console.WriteLine("{0} {1}", timeValue.Time, timeValue.Value);
}As you can see in the Console Output below, 3 time-value pairs are actually returned, matching the
Task.FuturePeriods property value specified in the previous section.
