Microsoft Project Codename Astoria

Getting Started

Introduction

The goal of Microsoft Codename "Astoria" is to enable applications to expose data as a data service that can be consumed by web clients within corporate networks and across the internet. The data service is reachable over regular HTTP requests, and standard HTTP verbs such as GET, POST, PUT and DELETE are used to perform operations against the service.

The payload format for the service is controllable by the application, but all options are simple, open formats such as plan XML and JSON. The use of web-friendly technologies make it ideal as a data back-end for AJAX-style applications, Rich Interactive Applications and other applications that need to operate against data that is across the web.

This document describes how to create and use Microsoft Codename Astoria data services, and discusses various details around the URL and payload formats. For an overview of the Project Astoria, see the “Project Astoria Overview” document. The first Astoria CTP is a dual release making Astoria available in the form of downloadable bits that can be used to build data services that are entirely contained within a single computer or network, and as an experimental online service that you can use to create online stores that are hosted by Microsoft and are accessible over the internet.

For a high-level introduction to the Astoria project and more information on the motivations and key elements that lead to this project, please view the Astoria Overview document, available on the Resources tab.

Before Starting

In order to create a web data service using Microsoft Codename Astoria in your own environment you will need Microsoft Visual Studio Codename “Orcas” Beta 1, and a database with updated data-access providers, such as Microsoft SQL Server 2005. In this document we will use SQL Server Express.

NOTE: This CTP release of Astoria works best with the Standard, Professional or Team System versions of Visual Studio Codename “Orcas”. While you can still use Visual Studio “Orcas” Web Developer Express edition, the experience is not optimal.

If you do not have access to the pre-release packages of Microsoft Visual Studio or Microsoft Codename Astoria, or would rather not install it, most of the examples discussed below can be accomplished using the sample online versions of the data service. For more information, and to begin working with the sample online versions of the data service, see the section “Getting Started Using the Astoria Online Service”.

Getting Started Using Astoria in your own Environment

After installing Visual Studio Codename "Orcas" Beta 1 and SQL Server Express Edition, download and install the Astoria toolkit.

This CTP release also includes pre-built samples that you can use to learn about the technology. These samples will allow you to see how data services are consumed using different client-side technologies such as .NET Framework clients and AJAX-style clients.

To use the samples provided, Start Visual Studio "Orcas". If you are using a Visual Studio Express Edition, open the SimpleWebSite sample from the Program Files\Microsoft Codename Astoria\Samples directory. If you are using Standard, Professional or Team System versions of Visual Studio, open the Simple NorthwindSample from the Program Files\Microsoft Codename Astoria\Samples directory. Once the project is open, hit Ctrl + F5 to start the development web server and launch the sample in an internet browser.

Both samples will bring you to a similar page that will allow you to Check for, and create if necessary, the required Northwind database. Once the database has been found, or created, you be able to begin to explore the data that has been exposed through the Astoria data service.

Creating a local data service using Visual Studio

Astoria data services are a specialized form of Windows Communication Foundation services, and they can be hosted in various environments. For this CTP release, Astoria services always run inside ASP.NET sites. In order to create a data service, you must first create a web project; you will then need to establish a connection with the database that you want to expose in the service, and then create the data service itself within the web application. Below is a step-by-step description of this process:

1. Create the project

Create a “Web Application” project, File -> New -> Project.
When the New Project window appears, choose either Visual Basic or Visual C# as the programming language, and within the language category click on “Web”, and select “ASP.NET Web Application” from the right-hand panel. Choose a name for the project, for example SimpleDataService, and click OK.
NOTE: if you already have a web application and you’d like to add a new data service to it, you can skip step 1 and go directly to step 2

2. Create an Entity Data Model representation of your database

Assuming that you already have a database that you want to expose as a data service, we will create an Entity Data Model schema that maps 1:1 with your database.
Select SimpleDataService -> Add New Item, in Visual Studio.
When the Add New Item window appears, choose “ADO.NET Entity Data Model”, give it a name and click Add. We will use the Northwind sample database throughout, so we will use “Northwind” as our name (Northwind.csdl being the generated file name).

When the Entity Data Model Wizard appears, select “Generate from Database” and click next.
Create a new connection to the database by using the “New Connection…” button, or use one of the available databases if you have one pre-configured, click next.
In the last window, the wizard presents the list of tables available from the database, you can leave the default selection or specify which tables you with to make visible through the service.
Click finish to close the wizard.

The wizard will generate files to represent the database metadata in the project. In the rest of the step-by-step guide we will assume you are using the Northwind example database, so the database connection created here should point to Northwind.

NOTE: if you are using SQL Server 2005, it is recommended that you create a new connection in this dialog (e.g. for Northwind) and in the “Connection Properties” window click on “Advanced”, locate the “MultipleActiveResultSets” option and set it to “True”.

3. Create a data service

To create the data service itself, select SimpleDataService -> Add New Item, in Visual Studio.
Choose “Web Data Service” from the list of item templates, give it a name (e.g. Northwind) and click add. (note that you need to select “Web Data Service”, not other similarly-called options such as “Web Service”.)

Visual Studio will open the code file for the new service by default. You can also find the file in the Solution Explorer; it will have the name you indicated, with a “.svc.cs” or “.svc.vb” extension.

Open the file, and add an “imports” (Visual Basic”) or “using” (C#) clause at the beginning of the file to include the namespace of the data classes generated by the wizard in step 2. You can use the Visual Studio object browser to locate the name, or just rely on intellisense. The namespace is derived from the database that was used for the data service, for example if the database was called Northwind the namespace will be NorthwindModel.

Locate the “TODO:” comment that indicates where to put the class name that represents the database, and replace it with the name of the class that was generated by the Entity Data Model Wizard in step 2. Again, the name is derived from the database name, so for example if the database is called “Northwind” the class will be “NorthwindEntities”.

At this point the data service is ready to use. It is setup with default access which exposes all the contents of the database directly through the service. Before deploying, you may want to adjust which parts of the database are visible, and of those which ones should be read-only and which ones read-write.

NOTE: the current CTP defaults to “all access” to make it straightforward to experiment with the technology. In the future you can expect security-oriented defaults that don’t expose anything unless it has been explicitly enabled

The code file (e.g. northwind.svc.cs or northwind.svc.vb) should look more or less like Example 1 or Example 2 depending on the programming language you are using.

using System;
using System.Web;
using System.Collections;
using System.Collections.Generic;
using System.Data;
using System.Data.Objects;
using Microsoft.Astoria;
using NorthwindModel;

namespace SimpleDataService
{
     public class Northwind : WebDataService < northwindentities >
    {
    }
}

Example 1

Imports System.Data.Objects
Imports Microsoft.Astoria
Imports NorthwindModel Public

Class Northwind
Inherits WebDataService(Of NorthwindEntities)
End Class

Example 2

To test the data service, simply hit Ctrl+F5 within Visual Studio, which will start the development web server and will run the server inside it. See the “Trying an Astoria Data Service” section below to walk through a trial run of your newly created data service.

Getting Started Using the Astoria Online Service

In addition to being able to create web data services using Visual Studio and deploy them on your own systems, this CTP release is also being experimentally hosted online by Microsoft.

For the online scenario, you can use some of the pre-created data services that are available as part of this CTP release. After the service has been created, the interaction with it is the same as the interaction with a locally created service.

Trying an Astoria Data Service

The easiest way to try an Astoria data service is to simply access it with the browser. While this is probably not the way you will ultimately use the data service (it is more likely that a program will interact with it), it is an easy way to understand how requests work, what results look like, and other details surrounding the implementation of the service.

To interact with the data service, open a web browser such as Microsoft Internet Explorer and point it to the URL that is the entry point to the site. If you created the data service locally using Visual Studio, you can simply hit Ctrl+F5 to start the web server, and then point the URL in the browser that Visual Studio launches to the data service file. For example, “http://host/vdir/northwind.svc” where “host” is a computer name or localhost; you may also need to add a port number. To use one of the pre-created online data services, you can click on the Astoria Online Service page.
When you hit the entry point, by default, you will get an XML response that contains the list of “entity-sets” (sort of tables in EDM parlance). In the Northwind example we’ve been using so far, the output will be similar to what is shown in Example 3 below.

< DataService xml:base="http://host/vdir/northwind.svc" >
   < NorthwindEntities uri="." >
   < Categories href="Categories" / >
   < Customers href="Customers" / >
   < Employees href="Employees" / >
   < OrderLines href="OrderLines" / >
   < Orders href="Orders" / >
   < Products href="Products" / >
   < Regions href="Regions" / >
   < Shippers href="Shippers" / >
   < Suppliers href="Suppliers" / >
   < Territories href="Territories" / >
   < /NorthwindEntities >
< /DataService >

Example 3

Using this as a starting point, you can start to browse deeper into the contents of the data service.

For more information and further detail on using the Astoria toolkit and online service, please view the Using Microsoft Codename "Astoria" document, available on the Resources tab.

This document supports a preliminary release of a software program that bears the project code name “Astoria”.

Information in this document, including URL and other Internet Web site references, is subject to change without notice and is provided for informational purposes only. The entire risk of the use or results from the use of this document remains with the user, and Microsoft Corporation makes no warranties, either express or implied. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2007 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Silverlight, SQL Server, Visual Studio, Windows, Windows Server, Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks are property of their respective owners.