I teach web programming courses. In our school (in early 2012), we are refreshing the introductory web programming courses to cover modern yet mainstream topics.

During our discussions, I was challenged to make my views clear and understandable to all, whether they were new to web programming, or whether they had past knowledge and experience. I thought about the challenge for awhile, and decided to publish this “one-page web programming course”. That was my goal – an introduction to web programming, for someone who is new to this topic, on one page. It fits on one web page (ha ha), and it fits on one printed page (with a small font size ☺ ).

Comments and feedback invited. The first time you read it, don’t stop to click the links. Just read it through. Then, you can go back and click the links to learn more, if you like.

.

One-page web programming course

You have decided to learn web programming. Well, you need to learn something about four things:

1. Web page definition, structure, and content
2. Web page appearance
3. Web page programming
4. Web page publishing

What is a web page? It is a document.

How do you view a web page? With a program called a web browser.

What does a web page contain? Content, and markup text. HTML is the markup language that’s used on web pages. The HTML markup will often also include CSS and JavaScript, which are explained later.

How is a web page organized? Does it have a structure? Yes. A web page (document) must conform to the document object model (DOM) standard. You should know three things about the DOM:

1. It describes a document’s parts or components (e.g. head, title, body, etc.).
2. A document is exposed as an object, which means that its structure and content can be manipulated (i.e. viewed, queried, changed, etc.).
3. The DOM broadcasts events (e.g click, mouse over, etc.), which enables a listener to perform an action.

What is HTML? As noted above, it is a declarative markup language that describes the structure and contents of a document. There are about 100 elements that can be used. All documents include a head element, and a body element. Within each of these, we add other elements (e.g. a title in the head, and structural divisions and content paragraphs in the body), and content.

The syntax used to describe document elements conforms to this format:

<element attribute1=”value1″>Optional content</element>

Notice the start “tag”, which begins with “<ele…”. Also notice the end “tag”, which places a slash character before the element name, e.g. “</ele…”.

How do we identify and locate document elements? There’s an easy way to identify and address document elements by their element name. There’s also an easy way to identify and address a selection of document elements, by using a programmer-specified “class name”, and marking the appropriate document elements to use the class name. Finally, there’s also an easy way to identify and address a specific document element, by marking the element with a programmer-specified unique identifier.

How can we change the document’s appearance? We use CSS rules. The way in which a programmer and designer can affect the document’s appearance is almost unlimited. To use CSS effectively, you must know about the document’s structure, the DOM.

What is CSS? It is a declarative language that is used to describe the appearance of an HTML document. The language statements are called rules. There are rules that affect layout and positioning, fonts, and visuals such as colours and images.

CSS rules can be placed in a separate source code file, and then linked to a document. Alternatively, CSS rules can be placed in the head of a document, or in a document element’s start tag.

The syntax used to describe CSS rules conforms to this format (when located in a separate source code file, or in the head of a document):

ruleName { rule1: value1; rule2: value2 }

The “ruleName” is known as a selector. It can be a document element name, a programmer-specified class name, or a programmer-specified unique identifier name.

How can we make a document interactive and functional? We use JavaScript.

What is JavaScript? It is a programming language that can access and manipulate a document. JavaScript is the programming language for web pages.

A document can display static content. However, a document can also be interactive and functional by using JavaScript. For example, the document’s structure, content, and appearance can be modified, based upon user interaction, or some other event or stimulus. JavaScript can also access the web, and fetch data from a web server. The new data can then be used to modify the document’s content and experience, if desired.

JavaScript source code can be placed in a separate source code file, and then linked to a document. Alternatively, it can be placed in the document (head or body), or in the document’s elements or content.

How can we make our document available to the public? We publish it to a web app.

What is a web app? It is a program, which runs on a web server, and responds to requests from browsers. The requests and responses conform to the HTTP protocol.

A web app can serve static resources (including web pages and images), which means that the web app simply retrieves the resource from the web server’s file system, and returns it to the browser.

However, a web app can also dispatch a request to an executable resource (i.e. a program), which will process the request, dynamically generate an appropriate response, and return it to the browser.

.

.

.

.

.

As a third- or fourth-year student, you have some experience with a number of programming languages. Let’s begin to learn about Objective-C by asking questions in the form of a “top ten” list. (Note that you can ask these questions about ANY language.)

Note: Objective-C is the name of the programming language. It adds a small number of object-oriented extensions to the standard C language.

Cocoa is the name of the the class library and runtime. The classes are organized into “frameworks”. Your app will link to one or more frameworks.

So, in summary, to create apps for iOS and Mac OS X, you write code using the Objective-C language, and use Cocoa classes.

.

The “top ten” list of questions

Here is the “top ten” list of questions to ask when learning Objective-C:

1. How do I create/edit/save the source code? What editor do I use? Where do I store the source code? What is the source code file naming convention?

2. How do I build/compile and then execute/run my program? Is there a compiler? Is there a host execution (aka “runtime”) environment?

3. What is the program’s entry point? Syntactically, what coding convention must I follow?

4. What data types can I use? Are they categorized (e.g. value/stack, reference/heap), and if so, what do I need to know about their characteristics (e.g. size, initial value, precision, convertibility, etc.)?

5. How do I declare new variables/fields of a data type? How do I instantiate them? How do I refer to and use these variables/fields? (Note that a type could be a class declaration for an object-oriented language and platform.)

6. What operators are available to me in this language? (How do they compare to other languages that I’m familiar with?)

7. What is the syntax of a statement, and of an expression? What delimiters are used? How is scope and hierarchy expressed?

8. What syntax enables me to process a decision (e.g. if-else, or switch-case)?

9. What syntax enables me to process repeatedly (e.g. for, while)?

10. How are functions (methods) declared? What rules are there for argument/parameter declaration? How are functions used/called? Are the arguments passed by value, or by reference?

Bonus:

11. Where do I get learning/tutorial information? Where do I get reference information? Where do I look for good-quality online information?

.

The answers

Here are the answers. We cover them in class, and we go through some examples.

1. How do I create/edit/save the source code? What editor do I use? Where do I store the source code? What is the source code file naming convention?

You write source code with Xcode, Apple’s integrated development environment (IDE).

An app is typically organized as a “project”, which appears as a folder in the file system. In that folder, your source code is stored in text files, and you will also find “resources” for your app, such as images, configuration settings, and so on.

Objective-C is a header-based language. You define a class’s interface in a text file that has a .h extension (e.g. Person.h). The class’s implementation code is located in a text file that has a .m extension (e.g. Person.m).

Most often, you create classes for your app. A class can be used to perform tasks (e.g. a “controller”), or it can be used to represent real-world objects (e.g. a “model”).

.

2. How do I build/compile and then execute/run my program? Is there a compiler? Is there a host execution (aka “runtime”) environment? Does it control the application lifecycle?

In Xcode, you can use a “build” command (or one of its variants) to build/compile your program. Its command key shortcut is Command+B.

To run your program, you first select an execution target (e.g. a simulator, or a device), and then you use a “run” command. Its shortcut is Command+R.

Cocoa is the execution runtime environment. Your app runs under the control of Cocoa. Cocoa sends your app messages when something happens in the environment (e.g. a user touches/taps the screen, or data arrives from the network.

In summary, Cocoa is in control.

.

3. What is the program’s entry point? Syntactically, what coding convention must I follow?

As a C-based language, the main() function is your app’s entry point. When a user starts/launches your app, the main() function runs.

For a typical iOS or Mac OS X app, main() calls a function that loads the app into the Cocoa runtime environment. At that point in time, as noted above, the Cocoa runtime is in control.

The Xcode project templates all include the main.m source code module, which has the main() function. Typically, you do not ever have to edit main.m.

.

4. What data types can I use? Are they categorized (e.g. value/stack, reference/heap), and if so, what do I need to know about their characteristics (e.g. size, initial value, precision, convertibility, etc.)?

Your apps can use C language types, and Cocoa types, in any combination.

Most of the time, you will prefer to use Cocoa types. For example, NSString offers rich functionality for strings. NSArray is a collection class, for elements/members of any Cocoa type.

C language types, including structs, are value (scalar) types.

Cocoa type instances are reference types. The instance name is a pointer to the memory that holds the instance’s data.

The initial value of a type instance varies by type. Sometimes, you get “nil”, or nothing. Other times, you get a working object, with empty or nil fields (properties).

As you would expect, most convertible types have methods which enable type conversion. For example, NSString has an intValue method, which attempts to return an integer of the string instance.

You can create your own types. Objective-C is a header-based language:

• The public interface (methods and properties) is defined in a source code file which has a .h extension. The definitions are placed between an @interface statement and an @end statement.
• The implementation code is located in a source code file which has a .m extension. The code is placed between an @implementation statement and an @end statement.

.

5. How do I declare new variables/fields of a data type? How do I instantiate them? How do I refer to and use these variables/fields? (Note that a type could be a class declaration for an object-oriented language and platform.)

For C language types, simply use the C language semantics. For example:

int i = 5;

For Objective-C (Cocoa) types, you must create an instance of the desired type. There are two ways to initialize a new object:

1. Use the type’s designated initializer
2. Use a “class method”

.

Using an initializer:

Most Objective-C types include one or more initializer methods. (In C# and Java, you know these methods as “constructors”.)

Almost every type supports the base initializer, called “init”.

A type designer can create more initializers, which can accept arguments. If there’s more than one initializer, the type designer will make one of them the “designated initializer”, which is the one that performs the initialization. (If the developer uses another initializer, that initializer will ultimately call the designated initializer.) Initializers should always begin with “init”.

The following shows two examples that use an initializer:

NSMutableString *s = [[NSMutableString alloc] init];

Person *p = [[Person alloc] initWithLastname:@”McIntyre” andFirstName:@”Peter”];

.

Using a class method:

Many Objective-C types offer one or more class methods that initialize a new object. (In C# and Java, these are known as “static methods”.)

They are also known as “convenience” (or “factory”) methods. They make it really easy to create an object. Initializer class methods may or may not accept arguments, it depends upon their design.

The following shows two examples that use class methods. Assume that “lname” and “fname” are existing NSString objects:

NSString *s = [NSString stringWithFormat:@"My name is %@ %@", fname, lname];

Person *p = [Person personWithFirstName:fname andLastName:lname];

.

As you would expect (in other languages), you refer to the new objects by using their instance name. You would simply use “s” to refer to the NSString object above. Or, “p” to refer to the Person object above.

As you would do in C, if you wanted the memory address of “s” or “p”, use the “&” symbol. So, the address of s would be “&s”.

As you would do in C, if you wanted the pointer to “s”, use the “*” symbol. However, as it turns out, this is infrequently used.

.

6. What operators are available to me in this language? (How do they compare to other languages that I’m familiar with?)

The standard C operators are available.

When working with objects, you will typically call an object’s methods, to perform operations, or access state through getters and setters. Some objects have properties, which you can access using a dot operator.

.

7. What is the syntax of a statement, and of an expression? What delimiters are used? How is scope and hierarchy expressed?

Standard C language rules apply for statements, expression, delimiters, scope, and hierarchy.

However, when calling a method on an Objective-C object, a square-bracket syntax is used. The syntax is obviously quite different from C and other C-family object-oriented languages.

In the example that follows, we “convert” a string, which is holding an integer, into a C scalar, by calling the string’s “intValue” method. (The string comes from a “Label” control – which is an object – in the user interface).

int n = [lblAge.Text intValue];

.

8. What syntax enables me to process a decision (e.g. if-else, or switch-case)?

Objective-C is a C-family language, so its statement syntax is similar. if-else (including the ? : syntax) and switch-case are available.

.

9. What syntax enables me to process repeatedly (e.g. for, while)?

Objective-C is a C-family language, so its statement syntax is similar. for and while are available. There is also a foreach enumerator form of the for statement.

.

10. How are functions (methods) declared? What rules are there for argument/parameter declaration? How are functions used/called? Are the arguments passed by value, or by reference?

Objective-C is a C-family language, so you declare and call functions in a similar way.

In an Objective-C class, you define (then implement) its public interface with methods and properties. There are two kinds of methods: 1) Class methods, and 2) Instance methods:

1. A class method can be called directly, without creating an instance of the class.
2. An instance method can be called on an instance of the class.

.

The definition of a method is similar to C, but there are two important differences:

1. The method definition (and implementation) is preceded by a + (plus sign) for a class method, and by a – (minus sign) for an instance method.
2. The method parameters (arguments) are named.

.

Here are a few examples, using the “Person” examples from above (in question 5).

// Instance method definition/declaration
- (NSString *)newPhoneNumber:(NSString *)phoneNumber forPhoneNumberType:(NSString *)phoneNumberType;

// Class method definition/declaration
+ (Person *)personWithFirstName:(NSString *)firstName andLastName:(NSString *)lastName;

.

The name of the instance method (above) is:

newPhoneNumber:forPhoneNumberType:

Notice that the name includes each argument, and the colons.

.

To call a method, use the syntax that you saw in question 5 above:

// Calling an instance method
Person *p = [[Person alloc] initWithLastname:@”McIntyre” andFirstName:@”Peter”];

// Calling a class method
Person *p = [Person personWithFirstName:fname andLastName:lname];

.

In Objective-C, the phrase “calling a method” is not used as a first choice. Instead, we use the phrase “sending a message (to an object)”, or more simply, “messaging”.

.

Parameters (arguments) are passed by value (like in C). However, please note that you often pass a pointer, so you are effectively passing a reference.

.

11. Where do I get learning/tutorial information? Where do I get reference information? Where do I look for good-quality online information? 

Your professor recommends the Apple developer documentation.

To get started, and learn effectively through discussion and demonstration, you must attend all lectures. Then, you can augment your learning with three kinds of Apple documentation:

1) Competencies Documents

Apple publishes two sets of well-written technology introductions. One set covers both iOS and Mac OS X, and is available here:

Cocoa Core Competencies

The other set covers topics that are specific to iOS:

Cocoa Application Competencies for iOS

Each document is a brief introduction to a topic, and includes links to a “definitive discussion” document, which is usually a developer guide.

.

2) Developer Guides 

Apple publishes a large number of developer guides. These documents range in size from tens of pages, to hundreds of pages. They include discussion, best-practice advice, code samples, and other information that’s valuable to the developer.

Developer guides are organized on a per-topic basis. You can see the complete list of guides by viewing the iOS Developer Library (after you login to the iOS Dev Center). On the left side, under “Resource Types”, click “Guides”.

A student should look for a developer guide after looking for and viewing a “competencies” document.

.

3) Reference Documents

Objective-C and Cocoa classes are well-documented in “reference” documentation. For a class reference (e.g. UITextField Class Reference), you will get overview information, as well as detailed syntax and usage for methods and properties.

.

The online iOS Dev Center is also your source for videos, code samples, Xcode information, and so on.

.

For non-Apple resources, the StackOverflow web site is acceptable. In addition, a few other web properties are useful from time to time, and they will be referenced in the notes during the semester.

Note: Your professor’s opinion is that you should avoid getting answers and code samples from search engine results. Typically, the information and code is low quality, and will distract you from learning the material. (Your professor is trying to be as kind as he can be with his phrasing here.)

.

.

.

.

This document was most recently updated in December 2011.

.

We have the following goals for this part of the course:

• Orient the iOS developer to Mac OS development, specifically Cocoa
• Leverage your existing knowledge
• Think about making a Mac OS companion for your iOS app
• Highlight a few interesting features of Cocoa for Mac OS apps

.

Getting started with Mac OS programming

The iOS developer can take advantage of what they know to get started with Mac OS programming. The language (Objective-C) is the same, and many of the Cocoa frameworks are the same.

The way in which data is persisted is the same. You can use a plist file (for arrays and dictionaries), archiving (for any type of object), and Core Data. The application also has access to data stored at network locations.

On iOS, the developer has UIKit, a framework with user interface classes that were designed for the iOS. On Mac OS, the developer uses AppKit, a richer set of user interface classes. The iOS offers the developer and user a single window, and a screen-at-a-time way of working with the application. The Mac OS enables the developer to use a larger screen, which allows the use of multiple windows.

Mac OS apps can be built as “document-based” applications, which means that the user is able to create, work with, and save document-oriented data. What format of data? What type? Well, it’s up to the developer. It can be as simple as a single data type (e.g. a text string in a text editor application), or a complex object graph, where (for example) a document consists of data that’s displayed in a tabular and/or graphical format, along with other data that helps make up a complete document. Document-based applications typically enable the user to “File > New” (Command+N), “File > Save” (Command+S), close (Command+W), and print (Command+P) documents.

When creating a new project, the Mac OS programming beginner will select one of the “Mac OS X” templates. For the first few projects, choose the Application > Cocoa Application template. Then, you can choose, with a check box, to create a document-based application, and/or use Core Data in your application.

A Mac OS app that doesn’t use either documents or Core Data gets created with the following:

• Application delegate – similar in function and purpose to the iOS implementation
• MainMenu nib – holds the menu choices, and a window object for the user interface

A Mac OS app that is based on the document-based template gets created with the following:

• MyDocument controller class – similar in concept to an iOS view controller class
• MainMenu nib – holds only the menu choices
• MyDocument nib – holds the window, the view (user interface), and works with the MyDocument controller

A Mac OS app that uses Core Data but isn’t a document-based app gets created with the following:

• Application delegate
• MainMenu nib
• Core Data model

A Mac OS app that uses Core Data and the document-based template gets created with the following:

• MyDocument controller class
• MainMenu nib
• MyDocument nib
• Core Data model

.

Memory management

Mac OS apps offer automatic memory management. This is new for iOS (4.x and earlier) developers, who must know and use memory management techniques.

Therefore, in Mac OS apps, you do not have to be concerned with reference counting, retain/release, and so on.

.

Example apps introduction

We have a number of example apps today:

• HelloWorld
• Bound slider
• Professors base
• Professors save and load

.

One is a real simple “hello world” app, that highlights a few differences between a Mac OS app and an iOS app.

The third app is actually one that we configure with a base level of functionality, and then add on some features in a subsequent version. In between, we look at an example that clearly shows the Cocoa Bindings feature.

.

HelloWorld sample app

The first sample app is HelloWorld. You can get it from the example apps download area.

It is a simple app, where you can enter text into a text field, click a button, and the text gets displayed in another text field.

Along the way, we do a few things that enable you to see how a Mac OS app is, or can be, quite different from an iOS app. Build your own app as you go through the sample app. Choose the “Cocoa Application” template, and don’t select any options for “document” or “Core Data”. Here are a few highlights of what you’ll experience:

Template contents: As you have learned, this kind of app includes an app delegate, a MainMenu nib, and little else. Open up the MainMenu nib, and you’ll see a “Window” object in the document window.

Controller class: To do some work, you’ll have to add a controller class. Click the Classes group, and add a new class. You will chose a “Cocoa Class”, specifically the “Objective-C class” (a subclass of NSObject). You will then add a reference to this new class in Interface Builder, by dragging an “NSObject” into the MainMenu nib’s document window, and setting its class name (to the name of the class you just created) on the Identity Inspector.

In your new class, you need to reference an NSTextField for the input area, another NSTextField for the output area, and a button. The text fields need to be marked with IBOutlet, and you’ll need to declare a method to handle the button click.

Back in Interface Builder, with the MainMenu.nib, add the two NSTextFields and the NSButton. Specifically:

• The “input area” NSTextField will be a multi-line wrapping NSTextField
• The “output area” NSTextField will be a multi-line label NSTextField
• The NSButton will be a “Push Button”

To replicate the full functionality of the HelloWorld sample app, you’ll have to add in the parts for speech synthesis. The program code is well-documented, so look at it for what-when-where-why info.

An iOS app’s screen is a constant size, and we’re always working with a screen at a time. A Mac OS app can have a resizable window area. Our sample app anticipates this, by enabling the user to resize the window. Smooth resizing is implemented mostly in Interface Builder, by setting properties in the Size Inspector. Focus on looking in this inspector, and experiment with your own version of the app.

For a bit more fun, our sample app allows resizing only to the same height-width proportion as the background picture. To do this, we implement a delegate method that helps us.

.

Information about user interface objects (controls)

The iOS programmer will notice differences in AppKit user interface objects – e.g. buttons, text fields, and so on – that are conceptually related to UIKit objects. For best results, do not assume that an AppKit object has the same properties and instance methods as its related UIKit object. Also, when you look in the documentation for a class member, you may not find what you’re looking for. In that situation, follow the object inheritance hierarchy, and look in the object’s parent, repeating this action until you find what you’re looking for.

For example, an AppKit NSTextField has the following inheritance hierarchy:

• NSTextField inherits from…
• NSControl, which inherits from…
• NSView, which inherits from…
• NSResponder, which inherits from…
• NSObject

To repeat, if you’re looking for a class member in NSTextField, and cannot find what you’re looking for, look in NSControl. Repeat with NSView etc. as required.

To help you get started working with text fields, note the following:

• To read the contents of an NSTextField, send the instance the “stringValue” message
• To write the contents of an NSTextField, send the instance the “setStringValue” message

.

Professors sample app (“Professors base”)

The second sample app is Professors. You can download the base version (ProfessorsBase) from the example apps download area.

Your iOS apps often included UITableView based views. This Professors sample app uses a Mac OS NSTableView to display information about a list of professors.

While the iOS UITableView is a one-column table, an NSTableView enables the display of multiple columns. Each column can display text (the default), or other data types. For our simple example, we’ll stick with text display.

When we worked with an iOS UITableView, we implemented delegate and data source methods to handle table view operations. Although we could do that in a Mac OS app, we won’t – instead, we’ll use Cocoa Bindings, a Mac OS technology that can simplify table view operations. You’ll see that you can create a functional table view with little or no code.

.

Introducing Cocoa Bindings

Cocoa Bindings can simplify table view operations, and any other situation where you want to bind user interface objects to data model objects.

The data model objects can be simple – a string or an int for example – or they can be more complex and real-world – like an array, dictionary, or Core Data managed object graph. For best results, expose the data model object(s) as properties.

To introduce Cocoa Bindings, get the “Bound Slider” example app. It has a user interface with a slider and a text label. When the slider value changes, the text label is updated with the new value. The view controller has an int property, and both user interface objects are bound to the property. The Bindings Inspector enables you to establish the binding.

The following image illustrates the binding relationship:

While the example app and the diagram above shows you how to bind to a simple and distinct data model object (i.e. the int), you may also need to bind to a collection of objects, to display for example, a table view (as in today’s Professors… example apps).

For this scenario, Cocoa offers an Array Controller object. The Array Controller is added to the window nib, and a reference is made from it to your data model object, which in today’s example, is an array called “professors” in the view controller. The professors array is exposed as a property, and holds instances of “professor” objects as its elements.

Then, user interface objects are bound to the Array Controller, by specifying a “key path” to the data model object properties. Ideal for use with a table view, an Array Controller has an “arrangedObjects” instance variable, which represents the data model object collection (as a result of its reference to – in today’s example – the “professors” array in the view controller). The user interface object specifies the arrangedObjects instance variable, and then the property name in a data model object.

Alternatively, if the user interface object is to be bound to a specific object (rather than the whole collection), the Array Controller’s “selection” instance variable (inherited from NSArrayController’s superclass, NSObjectController) is the binding key. This scenario is used for one-of user interface elements, like a text label or an image.

The following image illustrates the binding relationship in the “Professors base” example app:

.

Continue working on the  ”Professors base” app

Now that you understand more about Cocoa Bindings, let’s continue building the app.

The first HelloWorld sample app was not a document-based application. Professors is, so as you’re following along, create a new Cocoa Application, and chose the “document” option. Notice that you get a MyDocument class and nib.

If you build and run, you will see that you get a fairly functional app from the template. You are able to create new (Command+N) document instances, close (Command+W) them, and so on. You can try saving (Command+S), but the save method hasn’t yet been implemented.

The next thing we want to do is to create a model class, “Professor”. This class will have properties for name, office, and photo. Nothing much is new here, when compared to the task in an iOS app. The class includes an init method overload that enables a fully working instance object to be returned.

Then, we will create an array that will be the data source for the table view. We do that in the MyDocument class. We configure it as a property, so that it will work with Cocoa Bindings.

Note: the screen captures are from Xcode 3.x on Mac OS X 10.6.x. They are a bit out of date, but not much. Time permitting, they will be updated. 

.

Now, we can create the user interface. It has two buttons (add a professor to the table view; delete a professor), a table view, and an image view (in which we’ll add photo support later). See the screen image on the right. On the window object’s Attributes Inspector, the “Resize” control has been unchecked/cleared, because we don’t want the user resizing the window.

After laying out the interface, do this: Drag an array controller from the library into the document window. On the Attributes Inspector, set the Class Name to “Professor”, and add the keys for the fullName, office, and photo properties. The keys match up to the model object’s properties, and are used by Cocoa Bindings. See the screen image below / to the left.

What did you just do? You added an array controller, and told it to work with “Professor” objects. In a minute, we’ll connect it to the “professors” array in the MyDocument class.

An array controller manages a collection of objects in a situation where we use Cocoa Bindings. The Cocoa Bindings technologies do a number of things for us, including reducing code dependencies, and synchronizing views when model data changes (and vice-versa). The array controller is a helper object, similar in a way that the “fetched results controller” is a helper object in an iOS app that uses Core Data and a UITableView.

So, the array controller knows it is working with “Professor” objects. Let’s connect it to the “professors” array in the MyDocument class. Click the Bindings Inspector (green rectangle and circle). In the Controller Content area, bind to File’s Owner (i.e. the MyDocument class), and enter “professors” in the model key path dropdown list. The other properties are fine as they are. See the screen image to the right.

The final array controller configuration task is to connect the “add” and “delete” buttons. Click to show the Connections Inspector. In the Received Actions area, click-and-drag the “add:” outlet to the add button in the user interface. Click-and-drag the “remove:” outlet to the delete button in the user interface. Your inspector panel should look similar to the example below.

OK… now it’s time to connect the table view columns with the “Professor” properties fullName and office. Double-click the table view column for the professor’s name, and the window should look similar to the screen capture image below, on the left. Now, in the Bindings Inspector for that column, set these properties, so that they appear similar to the screen capture image below, on the right.

• Bind to Array Controller
• Controller Key is arrangedObjects (which is the “professors” array we just pointed to above)
• The Model Key Path is fullName (that’s what we want to show up in the table view column)

Continue by configuring the office column. Double-click the table view column for the professor’s office, and the window should look similar to the screen capture image below, on the left. Now, in the Bindings Inspector for that column, set these properties, so that they appear similar to the screen capture image below, on the right.

• Bind to Array Controller
• Controller Key is arrangedObjects
• The Model Key Path is office

Save your work. At this point, you’ve configured an array controller helper object, and configured it to bind to the “professors” array. Run your app, and you will see that you can add and remove professors from the list.

The final thing we want to do with this app is to add the ability to drag-and-drop a professor’s photo into the image area of the app. It turns out to be easy to do. Click to select the image view. In its Bindings Inspector, set these properties, so that they appear similar to the screen capture image to the right.

• Bind to Array Controller
• Controller Key is selection this time; we’re relying on a selected professor in the table view list
• The Model Key Path is photo
• Conditionally Sets Editable is checked

Run your application again. Make sure you have created and selected (highlighted) a professor on your list. Now, open a Finder window that contains some photos, or a web page in Safari. Click, drag, and drop a photo into the image box on the app.

.

Professors sample app, enhanced (“Professors save and load”)

The third sample app extends Professors. You can download the enhanced version, ProfessorsSaveLoad, from the example apps download area.

As the name suggests, it adds the ability to save your list of professors as a document, and to load it up again.

We are going to use “archiving”, the same technology that we used on the iOS apps many weeks ago. To review, we have to configure the model class to know how to archive itself, and then we’ll implement methods in the controller that will take care of the saving and loading.

The first task is to edit the Professor .h interface to conform to the NSCoding protocol. Next, in its .m implementation, implement the initWithCoder: and encodeWithCoder: methods, as shown below.

Next, we write some code for some existing MyDocument controller methods that we’ve ignored up to now.

The dataOfType:error: method implements saving. It runs when the user chooses “Save” from the File menu (or presses Command+S), provides a file name, and clicks the save button. To make it work, make it return an NSData as shown below:

The readFromData:dataOfType:error method implements loading. It runs when the user chooses “Open” from the File menu (or presses Command+O), selects a file/document, and clicks the open button. To make it work, read (load) the data, place it into the “professors” property, and return YES, as shown below:

Finally, we need to change some settings for the overall app that it and Mac OS will be able it to recognize the documents the app works with. Expand/open the “Targets” group, right-click the “Professors save and load” app, and choose Get Info. Click the Properties tab. This sheet enables us to configure information about the documents that this app works with. Here’s what to do. For more information, consult the reference documentation.

Near the top, change the “Identifier” to a unique identifier – use some of your name for this, and the last part will be the app’s name.

In the Document Types list, change the only entry, so that it has the following properties:

• Name – Professors document
• Extensions – profs
• OS Types – empty/blank/null

Close the dialog box to save your changes. See below for a before and after view of this dialog box.

Before…

After…

Now, run your app. The save and load/open operations should work.

.

Summary

This Mac OS programming introduction has shown you some of the similarities with iOS programming, and it has highlighted a few interesting capabilities that are available only on Mac OS apps. Take your time reviewing today’s notes, and recreate the examples on your own.
.

.

.

.

It is the second in a two-part series. This document was most recently updated in December 2011.

.

Introduction

In the previous post, you learned how to create a simple SOAP XML Web Service, by using the WCF Service item template. Here, you will learn how to add an Entity Framework data model to a service.

The scope of this post is modest. We will NOT be presenting a general-purpose n-tier approach. Part of the reason is that we cover this topic – SOAP XML Web Services – as a minor part of the overall course, in about three class and lab sessions.

We will, however, take advantage of the overall design and approach to modern SOAP XML Web Services development. The protocol and the standards, combined with the tooling, make it surprisingly easy to get good results with a reasonable amount of learning and effort.

.

Configuration of our solution

We will use a copy of the Northwind database in our solution.

For this task, we will also organize our work by using “projects”. (In past tasks, we have used the “web site” as the container.) We need a project feature – the ability to easily hard-code a port number for the ASP.NET Development Server – to simplify our learning task.

The image to the right shows the desired result for this section of the post.

To get started, create a new project, which will simply be a solution “container”:

File > New > Project…

On the left-side navigator, under Installed Templates, choose:

Visual C# > Other Project Types > Visual Studio Solutions

In the center panel, choose Blank Solution. At the bottom of the dialog, enter an appropriate name (e.g. “WebServiceSolution”), and select a location (which will be a file system location).

The solution’s folder/directory will be a container for two projects:

1. A web service
2. A client that will call the web service

.

Continue by creating the web service. In Solution Explorer, right-click the solution, then choose Add > New Project…

On the left-side navigator, under Installed Templates, choose Visual C#.

In the center panel, choose WCF Service Application. At the bottom of the dialog, enter an appropriate name (e.g. “WebService”), and make sure its location is the solution folder/directory from above.

Next, we need to configure a static port for the web service. This will ease our development process. Right-click the project, and choose Property Pages. On the Web tab, choose/select a fixed/static port. Save (Ctrl+S) your changes.

Continue by creating the client. In Solution Explorer, right-click the solution, then choose Add > New Project…

On the left-side navigator, under Installed Templates, choose Visual C# > Web.

In the center panel, choose ASP.NET Empty Web Application. At the bottom of the dialog, enter an appropriate name (e.g. “Requestor”), and make sure its location is the solution folder/directory from above.

Next, we should configure a static port for the client. As above, this will ease our development process. Right-click the project, and choose Property Pages. On the Web tab, choose/select a fixed/static port. Save (Ctrl+S) your changes.

Before continuing, compare your work to the image shown above. Build/compile, to make sure that there are no errors or warnings.

Note about build/compile:

The build/compile step is important for a “project”. If you change your markup or your code, you must do a build/compile. If you don’t, your changes will not be implemented in the exe/dll.

This is different from a “web site”, which has a build/compile-on-demand feature.

.

Important WCF Service principles

You have learned some basic principles of a WCF Service, and how it implements a SOAP XML Web Service:

• The “A” in “ABC”, address, is the publicly-accessible endpoint of your service.
• The “B”, binding, is (obviously) HTTP, as a SOAP XML Web Service.
• The “C”, contract is defined in the service interface, and implemented in the service class. A service contract will define the service’s operations, and a data contract will define the shape of the data that the service works with.

.

There are a number of other principles that affect our design and coding decisions, covered next.

For custom types (e.g. our own types, and/or the types that describe the Northwind entities, like Product, Supplier, Category, etc.), you must define a data contract. This enables the serializer, DataContractSerializer, to do its work. A data contract requires you to mark a class with attributes.

If the type defines a circular reference, then the data contract attribute must be:

[DataContract(IsReference=true)]

However, the framework will also support unmarked types. This enables us to use POCO (Plain Old CLR Objects) types, such as those generated by the Entity Framework editor’s code generator.

To use POCO types with an Entity Framework data model, the entity names much match.

Each property must match up too (names and types). A property’s POCO type must be concrete (i.e. it cannot be an Interface). A property cannot use the “virtual” modifier.

Incidentally, for your information, the support for unmarked types is an example of “coding by convention“. This software design paradigm is present in other areas of WCF Service development.

For best results, you must configure the context to disable (i.e. set to false) proxy generation, and lazy loading. (If you need eager loading, then use Include() in the query.)

In a client, when a Service Reference is created, the client has a definition of the web service class, and all of its operations. From the client’s perspective, return types can include:

• Scalar / primitive types
• Generic dictionary
• Entity types (more on this in the next section)
• Collections, which are materialized as arrays (of… whatever type the web service sends)

.

Implementing these principles

Now that the principles have been established, we can begin our implementation. Here is a preview of our work:

In the web service project, we will create an Entity Framework data model.

Next, we will generate entity classes. These classes must be edited, to follow the “unmarked types” principles above.

Then, we will define and implement service operations (i.e. methods).

In the client project, we will add a Service Reference. This will create a proxy of the web service. What’s interesting is that the client will have a definition for the web service class, and all of its operations, and it will have definitions for the entity types.

We emphasize here again: As a result of the Service Reference creation, the client will have definitions for the entity types. This will enable the client to work with instances (and collections) of entity types. Put another way, the client will be able to (for example) fetch a specific “Product” or “Employee”, enable the browser user to edit it, and return/save the changes, all while knowing the object’s properties and structure.

.

Scope of our in-class efforts

As noted above, we will work with a copy of the Northwind sample database. The Entity Framework data model will include three entities: Product, Category, Supplier.

The web service will include these operations:

• Return the number of products in the data store (as an integer)
• Return a list of supplier names (as strings)
• Return a collection of categories
• Return a specific category
• Accept and save an edited/changed category

.

Data model and generated classes

In the web service project, create an Entity Framework data model. Include only these database tables in the data model:

• Products
• Categories
• Suppliers

.

Build/compile your work before continuing. Note that you may have to use the NuGet Package Manager to get the EntityFramework package.

Next, generate entity classes. Use the DbContext generator. Note that you may have to download this generator template.

Then, edit the entity classes. Follow the “unmarked types” principles above:

• Properties must be concrete types (not interfaces)
• Properties cannot be virtual

.

Suggestion: The Category class includes a Picture property. In our example today, we will not need it. Therefore, mark that property with the [IgnoreDataMember] attribute.

(You can delete/remove the text templates – the .tt files – if you wish. If you need to re-generate your classes later, you can always do so.)

.

Work on the web service

As the comment suggests, you may want to re-factor your code, to change “Service1″ to “Service” (i.e. without the digit “1″).

In your web service interface, define the service operations (methods).

Next, implement the methods in the web service class. Pay attention to the return types. Use the general approach and technique you used while working on your WCF Web API services.

Build/compile your work before continuing, and ensure that the results are clean (no errors or warnings). Run the service, to ensure that you see the service start page.

.

Work on the client

Add a Service Reference to the project. A suggested name is “RemoteService”. The process will create a namespace – RemoteService – and classes for the web service itself (ServiceClient), as well as the entity classes.

Add an ASP.NET Web Form (Default.aspx) to the project. You will use this page to show the results of web service requests, and/or as a launcher to other pages that do the work.

Build/compile your work before continuing, and ensure that the results are clean (no errors or warnings). View the page in a browser after you do this.

.

Summary and wrap-up

The .NET Framework, and Visual Studio, work together to enhance your productivity when creating a SOAP XML Web Service.

Get more practice by completing Lab 5.

.

.

.

.

It is the first in a two-part series. This post uses an in-memory (per-instance) data store. The next post will use a persistent data store, accessed through the Entity Framework.

This document was most recently updated in November 2011.

.

Introduction

At this point in the semester, you have some experience with one of the two styles of web services, RESTful. SOAP XML Web Services is the other style that you’ll encounter. Here are some key ideas that will help you get oriented with SOAP XML Web Services:

• The plain-text data interchange format is XML
• The XML conforms to SOAP
• Often, a SOAP XML Web Service is published on a single (URL) endpoint
• The service includes one or more methods; each method may accept parameters, and may return data
• Service discovery is built in to the specification/standard
• Requestors use GET or POST requests to interact with the web service
• Requestors can use the service discovery feature to create a proxy class that models the web service (in fact, this is typical with most programming platforms)

.

On the Microsoft Web Platform, WCF technology is used to create SOAP XML Web Services. Version 4 of the .NET Framework improved the design and coding experience, and we will use version 4 in this two-part series. Scan the following article, and read about the WCF and web services topics:

What’s new in WCF 4 article

FYI – legacy versions of the Microsoft Web Platform used “asmx” item types to host SOAP XML Web Services. They were easy to create, but they were a solution for a very limited set of use cases. Do not use “asmx” item types for new web services. Scan the following article to read about the differences:

Legacy info on the difference between asmx and wcf web services

.

What is a WCF Service?

In Visual Studio 2010, a SOAP XML Web Service is created as a WCF Service. The following will introduce WCF Service concepts and topics.

A WCF Service is a program that exposes one or more endpoints, each of which exposes one or more service operations.

An endpoint specifies:

1. An address where the service can be found (e.g. http://host.domain.com/contacts.svc)
2. A binding that tells the client how to communicate with the service (e.g. HTTP)
3. A contract that defines the service’s functionality (e.g. it will do “this task” and “that task”)

.

Creating a WCF Service

You create a WCF Service in Visual Studio 2010. It is an (item type) that you can add to a Project or a Web Site.

A Web Site is software and resources that you create in a specific folder/directory. A Web Site must be hosted on a web server (e.g. either the ASP.NET Development Server, or a Microsoft Web Platform server). You can deploy a Web Site using a simple copy operation. The web server will compile and execute an endpoint upon request.

.

A Project is software and resources that you create in a specific folder/directory. A Project can be hosted on a web server, or on another kind of host (e.g. an executable, or a Windows Service). You must compile (build) the project (which creates an executable, either a dll or an exe) before you deploy it.

.

The default WCF Service item type (that you create with Visual Studio 2010) will create three software objects:

1. A publicly-accessible endpoint

2. A C# code-behind for the (above) publicly-accessible endpoint, which implements…

3. A C# interface that describes the “service contract” and “service operations”

.

The following sections include important information about each object.

.

Publicly-accessible endpoint

You pick the name (e.g. “Contacts”), it adds a “svc” extension (e.g. “Contacts.svc”).

You don’t add code to this endpoint.

.

C# code-behind for the (above) publicly-accessible endpoint

This code file is located in the App_Code folder/directory.

For example, continuing to use the name above, it will be called “Contacts.cs”.

.

C# interface that describes the “service contract” and “service operations”

A “service contract” is an agreement to define and provide a number of “service operations”. An interface is used as the code container for both. By convention in the .NET Framework, an interface name begins with an upper-case letter “I”. The second letter is also upper-case.

For example, continuing to use the name above, the interface will be called “IContacts.cs”.

Each “service operation” is a method. The method will have a return value, and a parameter list.

Although not required, it is a best practice to use an interface to declare the “service contract” and “service operations”.

What is the relationship between the interface and the (class) implementation?

• The interface defines the service’s methods.
• The implementation contains code for these methods.

.

Method return values and parameters

As noted earlier, a method will have a return value, and a parameter list.

The types must be serializable (obviously).

Primitive types are serializable by default. Many other types in the .NET Framework are also serializable by default.

If you create your own types (e.g. Product, Supplier, Contact, Address, Customer, etc.), then you typically “mark” your types (with “attributes”) to define a “data contract”.

A “data contract” is an agreement to define and provide a number of “data members”. The default WCF Service item type adds the “data contract” to the interface code container.

For example, continuing to use the name above, it will be added to “IContacts.cs”.

Each type is a class (as it always is). You typically add the [DataContract] attribute to the class.

Public properties are used to define the publicly-accessible data members.

Each serializable property gets the [DataMember] attribute.

.

Creating a client requestor

When working on RESTful web services earlier in the semester, you learned that you could interact with your web service by using a browser, or an HTTP requestor like your Lab 1, Fiddler, or your service’s HTTP Test Client.

With SOAP XML Web Services, some of the same techniques can be used. However, the message packaging format is SOAP XML, which can be inconvenient to manually enter into a request.

Another approach is to create a client requestor. Conceptually, it will be similar to your Lab 1, because it will be able to make a request to the web service, and receive (and process) the response. That’s what we’ll do here, by creating an ASP.NET Web Forms client requestor.

The key concept is to create a proxy, which will “model” the web service. Visual Studio has built-in tooling for this. Right-click the (web site) root, and select “Add Service Reference”. This will enable you to connect to the web service, discover its functionality, and have Visual Studio create a local proxy of your web service’s classes.

Then, in your web form code-behind, you simply 1) create an instance of the proxy, and 2) call its methods.

.

On your own – create a web service, and a client requestor

Your task:

In a new empty web site, create a service with two methods.

Method 1 will simply return your name (firstname last name) as a string.

Method 2 will return a collection (of strings) of your current-semester Seneca course codes (e.g. WSA500, SYS566, etc.).

In another new empty web site, create a (Default.aspx) web form that will call and display the data from the web service. Use Label web server controls for the data.

.

Preview of the topics we’ll cover in the next lecture

A blogger’s two-part series:

service create, and service consume (from Silverlight)

Another blogger’s article, some ideas are OK

Another blogger’s article on “what is an interface“

WCF and EF on StackOverflow - data contracts

.

Reference articles

Learn C# page

Interfaces - C# Programming Guide

Inheritance - C# Programming Guide

C# Language Fundamentals

.

.

.

.

This post was most recently updated in October 2011. It is intended for programmers in a degree-level academic program that focuses on software development. This post will likely be updated a few times in the near future, to add more detail and information.

.

A brief survey of sequence diagram creation toolsets

Students in Seneca’s ICT software development programs learn to use Rational Rose to create sequence diagrams, and other software system design modeling assets.

Visual 2010 Ultimate Edition now includes tooling that enables the creation of sequence diagrams.

Online, there are many tools that are offered, in both free and pay-for versions. In the following section, we’ll look at one of these tools.

.

Websequencediagrams.com

Websequencediagrams.com is an online tool that enables you to create and save sequence diagrams. Its syntax is easy and discoverable. It enables you to save your work in a PNG image, a PDF, or as source text. It also provides online tooling, via an API.

A recent post by the author (Web service security principles – OAuth 2.0 example) included two sequence diagrams.

The source text for the first diagram is below:

.

participant Resource\nOwner as RO
participant "Web\nBrowser" as ClientUI
participant Client\nApp as Client
participant Authorization\nServer as AS
participant Resource\nServer as RS

RO->ClientUI: [1] want protected resource
activate RO
activate ClientUI

ClientUI->Client: [2] GET protected resource
activate Client

Client-->ClientUI: [3] HTTP 302 redirect
deactivate Client
deactivate ClientUI

ClientUI->AS: [4] GET authentication UI
activate ClientUI
activate AS
AS-->ClientUI: [5] respond with authentication UI

ClientUI-->RO: [6] view authentication UI

RO->ClientUI: [7] enter credentials
ClientUI->AS: [8] POST the credentials

AS-->ClientUI: [9] HTTP 302 redirect to redirection endpoint
deactivate AS
deactivate ClientUI

ClientUI->Client: [10] GET auth grant exchanged
activate ClientUI
activate Client

Client->AS: [11] POST request access token
activate AS

AS-->Client: [12] respond with access token
deactivate AS

Client-->ClientUI: [13] HTTP 302 redirect
deactivate Client
deactivate ClientUI

ClientUI->Client: [14] GET protected resource
activate Client
activate ClientUI

Client->RS: [15] GET protected resource (with access token)
activate RS

RS-->Client: [16] respond with the resource
deactivate RS

Client-->ClientUI: [17] render resource in browser

deactivate Client
ClientUI-->RO: [18] view the resource
deactivate ClientUI

deactivate RO

.

The source text for the second diagram is below:

.

participant Resource\nOwner as RO
participant "Web\nBrowser" as ClientUI
participant Client\nApp as Client
participant Authorization\nServer as AS
participant Resource\nServer as RS

RO->ClientUI: [1] want protected resource
activate RO
activate ClientUI

ClientUI->Client: [2] GET protected resource
activate Client

Client->RS: [15] GET protected resource (with access token)
activate RS

RS-->Client: [16] respond with the resource
deactivate RS

Client-->ClientUI: [17] render resource in browser

deactivate Client
ClientUI-->RO: [18] view the resource
deactivate ClientUI

deactivate RO

.

.

.

.

This document was most recently updated in October 2011. It is intended to be used by entry-level web service programmers.

.

Overview of the scenario

Token-based schemes are often used for web services that require security. Recently, in class/lecture, we described many of the relevant security principles, and the implementation components, using the OAuth 2.0 Authorization Protocol as an example.

This post includes code that illustrates the bare essentials of handling an access token.

Warning – The code below is NOT a reference sample, or a best practice example. It simply illustrates the concept, in a clearly-understandable manner. Also, it does NOT deal with authentication and authorization issues, authorization stores, or the other “moving parts” that a full and complete solution includes.

.

Sample service code

Use your template to create a new WCF Web API service. Code the service class as follows:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
// Web service namespaces
using System.ServiceModel;
using System.ServiceModel.Web;
// Additional namespaces
using System.Net;
using System.Net.Http;
using Microsoft.ApplicationServer.Http.Dispatcher;
using System.Net.Http.Headers;

[ServiceContract]
public class Operations
{
    // Custom authorization token
    public string customToken { get; set; }

    // Collection of access tokens, which will be an in-memory "authorization store"
    protected List<string> AccessTokenStore;

    // Constructor
    public Operations()
    {
        this.customToken = HttpContext.Current.Request.Headers["X-ICTtoken"];

        // Un-comment the following if you want to protect the whole service
        //if (this.customToken != "whatever")
        //    throw new HttpResponseException(HttpStatusCode.Forbidden);

        // Create an in-memory "authorization store", with a few access tokens
        AccessTokenStore = new List<string>();
        AccessTokenStore.Add("triUt6ustoeQ");
        AccessTokenStore.Add("KOEn4Ejouqle");
        AccessTokenStore.Add("rIuv5u7hoeno");
        AccessTokenStore.Add("y7UcIeJ9eCIa");
        AccessTokenStore.Add("Joestievief9");
    }

    // Remove this method from an in-production (deployed) web service
    [WebGet(UriTemplate = "")]
    public string ServiceRoot()
    {
        return "Append /test to the URI to use the HTTP Test Client";
    }

    [WebGet(UriTemplate = "example1")]
    public List<string> Example1(HttpRequestMessage request)
    {
        // Get the authorization header
        AuthenticationHeaderValue auth = request.Headers.Authorization;
        // The scheme should be "Bearer", and the parameter should be the access token

        if (auth == null)
        {
            throw new HttpResponseException(HttpStatusCode.Unauthorized);
        }
        else
        {
            // Create a response object
            List<string> response = new List<string>();
            // Report the results
            response.Add("The authorization scheme was: " + auth.Scheme);
            response.Add("The parameter was: " + auth.Parameter);

            // Check if the access token is in the store
            if (AccessTokenStore.Find(t => t == auth.Parameter) == null)
            {
                response.Add("The access token was NOT FOUND in the authorization store");
            }
            else
            {
                response.Add("This is a valid access token");
            }

            return response;
        }
    }

}

.

Test your service

Run the HTTP Test Client for the service.

Request the “example1″ URI. It should respond with 401 unauthorized.

Now, add an “authorization header”:

Authorization:Basic foobar

The response should appear as follows:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <string>The authorization scheme was: Basic</string>
  <string>The parameter was: foobar</string>
  <string>The access token was NOT FOUND in the authorization store</string>
</ArrayOfString>

.

Next, change the authorization header:

Authorization:Bearer rIuv5u7hoeno

(or one of the valid authorization codes)

The response should appear as follows:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <string>The authorization scheme was: Bearer</string>
  <string>The parameter was: rIuv5u7hoeno</string>
  <string>This is a valid access token</string>
</ArrayOfString>

.

.

.

.

This document was most recently updated in October, 2011. It is intended for entry-level web service programmers.

.

Introduction to the scenarios

This post describes the use of a web service to deliver resources to requestors. The web service’s resources will be protected, and requestors must use the OAuth 2.0 Authorization Protocol.

A separate client app, perhaps an ASP.NET Web Forms app, would be used to request resources from the web service. Users of the client app will be able to request their own resources after authenticating.

The first scenario covers the use case where a client app, which does not yet have a valid access token, requests a protected resource.

The second scenario covers the use case where a client app, which has a valid access token, requests a protected resource.

.

OAuth 2.0 Authorization Protocol information

The OAuth 2.0 Autorization Protocol is described in draft-ietf-oauth-v2-22.

As suggested by its name, it is an Internet-Draft specification. As noted in the document:

It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.

Accordingly, in this post, we will use it as “working document” to enable security on a web service.

OAuth defines four roles:

1. Resource owner – An entity (e.g. an end user) capable of granting access to a protected resource.
2. Resource server – A server that hosts a protected resource. It responds to requests by validating an access token.
3. Client – Also known as a client app, this is an application that makes requests for a protected resource, on behalf of the resource owner, and with its authorization.
4. Authorization server – A server that authenticates resource owners, client apps, and issues access tokens.

.

OAuth is a protocol that enables a client app to use an access token to request a protected resource. The access token is issued to the client app by an authorization server, with the approval of the resource owner.

There are two defined client app types:

1. Confidential – Capable of maintaining confidentiality of client app credentials.
2. Public – Incapable of maintaining confidentiality of client app credentials.

.

There are four defined flows or scenarios that enable a resource owner to authorize the issuance of an access token:

1. Authorization code – A resource owner is able to authenticate directly with an authorization server, and passes on an “authorization code” to the client app.
2. Implicit – For client apps which are implemented in a browser using a scripting language (such as JavaScript).
3. Resource owner password credentials – Where there is a high degree of trust between the resource owner and the client app (e.g. a trusted client app on a resource owner’s mobile device).
4. Client credentials – For access to protected resources that are under the control of the client app (and not any specific/individual resource owner).

.

This post will cover the first flow/scenario, “authorization code”, with a “confidential” client.

.

Scenario terminology and assumptions

This post uses terminology from the OAuth spec, plus the following:

UI = user interface

Web browser = an HTTP requestor application that renders HTML content

Client app = web app, an executable that runs on a web server

.

The following diagram is a high-level overview of the components.

.

The authorization server and the resource server share an authorization store. The authorization store holds the following kinds of information collections:

• resource owner credentials
• client app credentials (which has a client app identifier that will be used by the web browser)
• authorization grant (which has a limited lifetime and scope)
• access token (which has a limited lifetime and scope)

.

For the following scenarios, the reader can assume that the resource owner credentials and the client app credentials already exist. Further, the authorization server has the programming, UI, and endpoints that enable the maintenance of these credentials.

The reader can also assume that the authorization server has the programming, UI, and endpoints that enable the maintenance of authorization grants and access tokens.

.

Scenario – first request for a protected resource

This scenario covers the use case where a client app, which does not yet have a valid access token, requests a protected resource.

This scenario is documented on a sequence diagram, shown below. Each signal is identified with a number in square brackets, [#], and you will find them in the text that follows.

.

How was this sequence diagram created? Click here and read this post for details. 

.

A resource owner, using a web browser, begins interacting with content in a client app. This begins a new “session” between the resource owner‘s user-agent (the web browser), and the client app.

The resource owner performs an action (e.g. clicks on a link or a button) [1] in the web browser, which causes a “GET protected resource” request to be created. The web browser sends the request to the client app [2].

Note: The web browser does NOT typically have/show the protected resource URIs from the resource server. The client app typically publishes (HTML) links that are in its domain, and maintains the mapping/lookup in its executable code.

In other words, you will typically NOT see this kind of link in the HTML markup of the web browser:

http://resourceserver.com/customer/3/

Instead, you will see this kind of link:

http://clientapp.com/customer/3

.

The client app asks “does this session have a valid access token?”

The answer will be “no”, because this is the first request for a protected resource.

Next, the client app asks “does the request from the web browser have a valid authorization grant?”

Again, the answer will be “no” (because this is the first request for a protected resource).

Consequently, the following sequence will be initiated, which will result in the acquisition of a valid access token:

1. The resource owner authenticates with the authorization server
2. The authorization server delivers an authorization grant to the client app
3. The client app requests that the authorization server exchange the authorization grant for an access token

.

Before continuing, the essence of the original “GET protected resource” request must be retained. The sequence (below) will include three (3) HTTP 302 redirects, and we will be unable to persist the original request in a query string parameter.

There are several state persistence schemes available to us. For example, the client app can save this information in session state. Or, it can be sent (in the following response) as a web browser cookie. Whatever scheme you select as the programmer, you just need to retrieve the value later, when you need it.

.

Sequence step 1: The resource owner authenticates with the authorization server

The client app responds back [3] to the web browser with the following:

1. a 302 redirect status code
2. a “location” header with the URI of the authorization server‘s authentication UI, and the following query string key-value pairs…
• response_type=code – for a typical interaction
• client_id= the client app identifier
• redirect_uri= a previously-established (between the client app and the authorization server) “redirection endpoint”

.

The web browser creates a new request, [4] “GET authentication UI”, and sends it to the (above) URI of the authorization server‘s authentication UI.

Note: The authorization server‘s authentication UI may be a specially-created page/interface, solely for the use of resource owners who want to authorize a client app. Alternatively, it may be the page/interface that is used by other general interactive users of the resource server.

.

The authorization server validates the request (to ensure that all required key-value pairs are present), and responds with the authentication UI [5], which will typically be an HTML form. (The key-value pairs are retained, in the URI query string, or in the authorization server‘s state management and persistence system.)

.

The resource owner views the form [6], enters their credentials [7], and submits them (typically with a button click). The web browser creates a [8] “POST resource owner credentials” request, and sends the request to the authorization server.

After successfully authenticating, the authorization server responds back [9] to the web browser with the following:

1. a 302 redirect status code
2. a “location” header with the URI of the client app‘s redirection endpoint, and the following query string key-value pair…
• code= the authorization grant (known as the authorization code) that was generated by the authorization server

.

Sequence step 2: The authorization server delivers an authorization grant to the client app

The web browser now has a valid authorization grant.

Using the URI from the response’s “location” header, the web browser creates a new request, [10] “GET authorization grant exchanged”, and sends it to the client app.

The client app inspects the request, which was received on the redirection endpoint, and asks “does the request from the web browser have a valid authorization grant?”

The answer will be “yes” (because a valid authorization grant was received on the redirection endpoint).

Before responding to the web browser, the client app continues with the following.

.

Sequence step 3: The client app requests that the authorization server exchange the authorization grant for an access token

A valid authorization grant can be exchanged for an access token. Therefore, the client app will create a new request, [11] “POST request access token“, and send it to the “token endpoint” on the authorization server. The request includes:

1. an “authorization” header, which includes the client app credentials
2. HTML form-encoded key-value pairs for the following parameters…
• grant_type=authorization_code
• code= the authorization grant (known as the authorization code) that was generated by the authorization server
• redirect_uri=the previously-established (between the client app and the authorization server) redirection endpoint

.

The authorization server will inspect the request. It validates the client app credentials (with a lookup to the authorization store). It validates the authorization grant (with a lookup to the authorization store). If successful, it responds with an access token [12].

The access token consists of a number of parameters, serialized as a JSON object, in the message body of an HTTP 200 response. The parameters include:

• access_token – string – the actual access token
• token_type – string – for example, “bearer”
• expires_in – integer, optional – the lifetime, in seconds, of the access token

.

Now that the client app has a valid access token, it typically persists it in session state.

The client app is now ready to respond to the “GET authorization grant exchanged” request from the web browser (in sequence step 2 above).

The client app creates a response [13] that includes the following information, and sends it to the web browser:

1. a 302 redirect status code
2. a “location” header with the URI of the original “GET protected resource” request (which may be retrieved from a web browser cookie, or the client app‘s session state)

.

Upon receipt, the web browser creates a [14] “GET protected resource” request, and sends it to the client app.

As above (when we started this journey), the client app asks “does this session have a valid access token?”

This time, the answer will be “yes”.

The client app creates a [15] “GET protected resource (with access token)” request, and sends it to the resource server. It includes:

1. a request URI for the actual resource
2. an “authorization” header that includes 1) the token_type, and 2) the access_token values

.

After validating the access token, the resource server responds back to the client app with the requested resource [16].

The client app now has the protected resource that was originally requested. The protected resource is rendered for the web browser [17], where it can be viewed [18] by the resource owner.

.

Scenario – subsequent requests for protected resources

This scenario covers the use case where a client app, which has a valid access token, requests a protected resource.

This scenario is documented on a sequence diagram, shown below. Each signal is identified with a number in square brackets, [#], and you will find them in the text that follows. The numbers used for the signals are the same as you saw in the first sequence diagram (but signals 3 through 14 inclusive aren’t there, because this scenario’s client app has a valid access token).

.

The resource owner performs an action (e.g. clicks on a link or a button) [1] in the web browser, which causes a “GET protected resource” request to be created. The web browser sends the request to the client app [2].

As above, the client app asks “does this session have a valid access token?”

As you would expect, the answer will be “yes”.

The client app creates a [15] “GET protected resource (with access token)” request, and sends it to the resource server. It includes:

1. a request URI for the actual resource
2. an “authorization” header that includes 1) the token_type, and 2) the access_token values

.

After validating the access token, the resource server responds back to the client app with the requested resource [16].

The client app now has the protected resource that was originally requested. The protected resource is rendered [17] for the web browser, where it can be viewed by the resource owner [18].

.

.

.

.

.

This post was most recently updated in October 2011.

.

XML and JSON are WCF Web API defaults

The WCF Web API services that you have created in the past work with XML and JSON data payloads. This capability is built in to the WCF Web API stack.

As a requestor, you indicate your desired data format:

• The “accept” header tells the service about the data format that you will accept, so the server will deliver the data in that format (e.g. “application/json”)
• The “content-type” header tells the service about the data format that you are sending in the request body with a POST or PUT request

.

When you write a web service method, it will have a return type, and some methods will accept arguments. The WCF Web API stack handles XML and JSON data formats by default.

The return type can be a data model object type, or a collection of them. Alternatively, a return type can be an HttpResponseMessage<T>, where T is a data model object type; this return type enables you to set other properties of the response message.

In either situation, the WCF Web API serializer takes care of serializing the data to the desired format.

For POST and PUT operations, where an object (or part of an object) is being sent to the method, the argument is a data model object type. A PUT handler will also include an argument which identifies the specific object to be updated. In addition, you can add an HttpRequestMessage argument, so that you can get access to properties of the request message.

In this situation, the WCF Web API serializer takes care of de-serializing the data sent with the request.

.

Delivering hypermedia

Delivering hypermedia – an image, a recording – is an uncomplicated task.

There are (at least) two ways to do this:

1. Use an HttpResponseMessage object
2. Use a MediaTypeFormatter

.

In this post, we will use an HttpResponseMessage object. (In a later post, we may cover the other way, using a MediaTypeFormatter.)

Assume that we have this scenario: We have a web service method, which handles GET. The method takes an argument, which is an identifier for a “photo” that will be delivered. The photo is (obviously) stored digitally, as a property of an entity. In addition, the photo’s MIME type is stored as a property of the entity.

Yes, the WCF Web API is still “new” in October 2011. Finding documentation and examples is a small challenge for an unreleased preview technology. However, we will persevere.

The return type of the method should (must) be HttpResponseMessage. It has two properties which must be set:

• Content
• Content.Headers.ContentType

.

The online help for the Content property tells us that it “Represents the content of a message. This corresponds to the entity body defined in RFC 2616.”

Its data type is System.Net.Http.Content, which is an abstract class. One of its concrete implementations is System.Net.Http.ByteArrayContent. When you examine this class’ documentation, you see that it has a constructor that uses a byte array. This matches the photo data that we have, so we can use it.

The online help for the Content.Headers.ContentType property is intended to hold the response’s “content-type” header value.

Its data type is System.Net.Http.Headers.MediaTypeHeaderValue. When you examine this class’ documentation, you see that it has a constructor that uses a string. This matches the photo MIME type that we have, so we can use it.

In summary, the method body has two lines of code that prepare the response. See the code sample below. Assume that the “photo” object is an typical model object, which has properties for storing hypermedia content and its MIME type.

    // Create a response object
    HttpResponseMessage response = new HttpResponseMessage();

    // Configure it with the photo content and the MIME type
    response.Content = new ByteArrayContent(photo.Content);
    response.Content.Headers.ContentType =
        new System.Net.Http.Headers.MediaTypeHeaderValue(photo.MIMEType);

    return response;

.

Accepting hypermedia

This course’s Lab 3 covers the task of accepting a photo in a WCF Web API service. It walks you through the coding tasks to re-purpose the Employees entity of the Northwind data store (or, in your copy, nwEmployees), so that you can store a modern format photo in the “Photo” property.

In general, when designing a web service method to accept hypermedia, you can obviously configure it for POST or PUT operations. The method body implementation will be almost the same (POST to a collection URI, and PUT to a specific object URI).

The method signature must include an HttpRequestMessage argument, so that you can get access to the request message headers and body. From the headers, you must extract the hypermedia’s MIME type. From the body, you must (obviously) extract the hypermedia.

In summary, the method body has two lines of code that accept the request data. See the code sample below. As above, assume that the “photo” object is a typical model object, which has properties for storing hypermedia content and its MIME type.

    // First, the hypermedia content...
    photo.Content = request.Content.ReadAsByteArray();
    // Next, the MIME type...
    photo.MIMEType = request.Content.Headers.ContentType.ToString();

.

Design considerations

When handling hypermedia, the way you design your methods is important.

Consider this scenario: You have an entity that describes a real-world object. It has many descriptive properties. It also has a hypermedia property (e.g. a photo).

When you GET a specific object, what do you expect to deliver/receive? Probably, a fully-serialized object, with the hypermedia data as part of the delivery package. This happens because the request’s default “accept” header will tell the service to serialize the object to XML or JSON.

What if you want the hypermedia only, in its native format (e.g. image/png)?

Should you create another method, which has another URI template (e.g. employee/{id}/photo)?

Or, should you enable the requestor to specify their desired data format in an accept header (e.g. accept: image/*), and process the request accordingly?

What about this slightly different scenario: You have an entity specifically for hypermedia (digital content). As such, it really is a container for hypermedia items. Typically, it is associated with other business entities.

How does this change your approach, given that a request for a specific hypermedia item fulfills the intent of the requestor?

The bottom line of all this is that you must consider your situation, and design and code accordingly. There’s no “one true way”, although some approaches are better than others.

.

.

.

.

.

This post was most recently updated in October 2011.

It is the third post in a multipart series on WCF Web API, and is intended to be used by students in Seneca’s diploma- and degree-level software development programs, and any other entry- to mid-level developer.

.

This post was inspired by…

The WCF Web API programming team discuss POST, PUT, and DELETE support in this note:

Adding support for… POST, PUT, and DELETE methods

We complement the coverage, by building on the first to posts in this series:

Getting started with a WCF Web API service

WCF Web API service with an Entity Framework data model

.

Make sure that you use your HTTP Test Client to prove that your service works correctly.

.

POST methods

The most important idea is that you must POST to a collection URI. Other features of a POST method:

• A WebInvoke attribute is used; the URI template should be the same as the one used to GET the collection, but its method must be “POST”
• It includes an argument for the new object to be added to the collection
• Its return type should be HttpResponseMessage<T>, so that we can set the status code
• The code adds the object to the context, and then saves changes

.

A sample method follows.

[WebInvoke(UriTemplate = "regions", Method = "POST")]
public HttpResponseMessage<nwRegion> AddRegion(nwRegion region)
{
    // FYI - you must supply a RegionID, because its key is NOT auto-incrementing

    // Add the region that was passed in as the argument
    context.nwRegions.Add(region);
    context.SaveChanges();

    // Prepare the response - we want to return "201 Created"
    HttpResponseMessage<nwRegion> response = new HttpResponseMessage<nwRegion>(region, HttpStatusCode.Created);
    return response;
}

.

PUT methods

The most important idea is that you must PUT to a URI for a specific object. Other features of a PUT method:

• A WebInvoke attribute is used; the URI template should be the same as the one used to GET a specific object, but its method must be “PUT”
• It includes an argument for the updated object, and the object key/ID
• Its return type should be the object’s type
• The code fetches the object to the context, and then saves changes/udpates

.

A sample method follows.

[WebInvoke(UriTemplate = "region/{id}", Method = "PUT")]
public nwRegion RegionUpdate(nwRegion region, string id)
{
    // Local variables
    int _id;
    nwRegion _object;

    // If the argument is not an integer, return an error
    if (!Int32.TryParse(id, out _id)) throw new HttpResponseException(HttpStatusCode.NotFound);

    // Attempt to locate the object
    _object = context.nwRegions.Find(_id);

    // If the object is null, return an error
    if (_object == null) throw new HttpResponseException(HttpStatusCode.NotFound);

    // Update the changed values
    context.Entry(_object).CurrentValues.SetValues(region);
    context.SaveChanges();

    return _object;
}

.

DELETE methods

The most important idea is that you must DELETE to a URI for a specific object. Other features of a DELETE method:

• A WebInvoke attribute is used; the URI template should be the same as the one used to GET a specific object, but its method must be “DELETE”
• It includes an argument for the object key/ID
• Its return type should be the object’s type (or HttpResponseMessage, with an empty Content property, and an HttpStatusCode of OK)
• The code fetches the object to the context, and then deletes it

.

A sample method follows.

[WebInvoke(UriTemplate = "region/{id}", Method = "DELETE")]
public nwRegion RegionDelete(string id)
{
    // Local variables
    int _id;
    nwRegion _object;

    // If the argument is not an integer, return an error
    if (!Int32.TryParse(id, out _id)) throw new HttpResponseException(HttpStatusCode.NotFound);

    // Attempt to locate the object
    _object = context.nwRegions.Find(_id);

    // If the object is null, return an error
    if (_object == null) throw new HttpResponseException(HttpStatusCode.NotFound);

    // Delete the object
    context.nwRegions.Remove(_object);
    context.SaveChanges();

    return _object;
}

.

On your own

In your web service, add methods that enable you to support POST, PUT, and DELETE. You will also get practice by doing Lab 2.

.

.

.

.