Data Source Controls (Part 1 - The Basics)

The sample
During the course of these posts, I'll be implementing a WeatherDataSource that works against the REST XML API provided by weather.com to retrieve weather information by zip code. I typically start by implementing the derived data source control.

public class WeatherDataSource : DataSourceControl {
    public static readonly string CurrentConditionsViewName = "CurrentConditions";

    private WeatherDataSourceView _currentConditionsView;

    private WeatherDataSourceView CurrentConditionsView {
        get {
            if (_currentConditionsView == null) {
                _currentConditionsView =
                    new WeatherDataSourceView(this, CurrentConditionsViewName);
            }
            return _currentConditionsView;
        }
    }

    public string ZipCode {
        get {
            string s = (string)ViewState["ZipCode"];
            return (s != null) ? s : String.Empty;
        }
        set {
            if (String.Compare(value, ZipCode, StringComparison.Ordinal) != 0) {
                ViewState["ZipCode"] = value;
                CurrentConditionsView.RaiseChangedEvent();
            }
        }
    }

    protected override DataSourceView GetView(string viewName) {
        if (String.IsNullOrEmpty(viewName) ||
            (String.Compare(viewName, CurrentConditionsViewName,
                            StringComparison.OrdinalIgnoreCase) == 0)) {
            return CurrentConditionsView;
        }
        throw new ArgumentOutOfRangeException("viewName");
    }

    protected override ICollection GetViewNames() {
        return new string[] { CurrentConditionsViewName };
    }

    public Weather GetWeather() {
        return CurrentConditionView.GetWeather();
    }
}

As you can see the basic idea is and implement GetView to return an instance of the named view, and GetViewNames to return the set of available views.

I chose to derive from DataSourceControl here. A subtle point that is not immediately obvious is that in reality the data-bound control looks for the IDataSource interface, which DataSource control implements using your implementations of GetView and GetViewNames. The reason we have an interface is to allow a data source control to be both tabular and hierarchical if appropriate (in which case you derive from your primary model and implement the other as an interface). Secondly, it allows transforming other controls in various scenarios to double up as data sources. (this approach has been pretty useful as part of a workflow framework I am prototyping for v-next)

Another thing to note is the public ZipCode property and the GetWeather method that returns a strongly-typed Weather object. This is the API that is geared toward the page developer. The page developer shouldn't have to think in terms of DataSourceControl and DataSourceView.

The next step is to implement the data source view itself. This particular sample only provides SELECT-level functionality (which is the bare minimum requirement, and the only thing that makes sense in this scenario).

private sealed class WeatherDataSourceView : DataSourceView {

    private WeatherDataSource _owner;

    public WeatherDataSourceView(WeatherDataSource owner, string viewName)
        : base(owner, viewName) {
        _owner = owner;
    }

    protected override IEnumerable ExecuteSelect(DataSourceSelectArguments arguments) {
        arguments.RaiseUnsupportedCapabilitiesError(this);

        Weather weatherObject = GetWeather();
        return new Weather[] { weatherObject };
    }

    internal Weather GetWeather() {
        string zipCode = _owner.ZipCode;
        if (zipCode.Length == 0) {
            throw new InvalidOperationException();
        }

        WeatherService weatherService = new WeatherService(zipCode);
        return weatherService.GetWeather();
    }

    internal void RaiseChangedEvent() {
        OnDataSourceViewChanged(EventArgs.Empty);
    }
}

The DataSourceView class by default returns false from properties such as CanUpdate etc. and throws NotSupportedException from Update and related methods. All that I needed to do here in WeatherDataSourceView is override the abstract ExecuteSelect method, and return an IEnumerable that contains the weather data that was "selected." In my implementation, I use a helper WeatherService class that simply uses a WebRequest object to query weather.com using the selected zip code (nothing magic in there).

You might notice that ExecuteSelect is marked as protected. The data-bound control actually calls the public (and sealed) Select method, passing in a callback. The implementation of Select calls ExecuteSelect, and invokes the callback with the resulting IEnumerable instance. This is a rather odd pattern. There is a reason behind it, and I'll get to it in a couple posts on this series. Stay tuned...

Here is an example of the usage:

Zip Code: <asp:TextBox runat="server" id="zipCodeTextBox" />
<asp:Button runat="server" onclick="OnLookupButtonClick" Text="Lookup" />
<hr />

<asp:FormView runat="server" DataSourceID="weatherDS">
  <ItemTemplate>
    <asp:Label runat="server"
      Text='<%# Eval("Temperature", "The current temperature is {0}.") %>' />
  </ItemTemplate>
</asp:FormView>
<nk:WeatherDataSource runat="server" id="weatherDS" ZipCode="98052" />

<script runat="server">
private void OnLookupButtonClick(object sender, EventArgs e) {
    weatherDS.ZipCode = zipCodeTextBox.Text.Trim();
}
</script>

The code sets the zip code in response to user input, which causes the data source to raise a change notification, which causes the bound FormView control to perform data-binding and update the display.

The data access code is now encapsulated in the data source control. Furthermore, this model could enable weather.com to publish a component that can in addition encapsulate the details specific to its service. Hopefully it will catch on. Furthermore, the abstract data source interface allows FormView to just work against weather data.

In the next post, I'll enhance the data source control with the ability to automatically handle changes in filter values (i.e. zip code) used to query data. By all means, send in your comments, if you'd like to drill further into a specific topic.