C# .NET Web Developer''''s Guide phần 10 pptx

ResponseNamespace="urn:schemas-syngress-com-soap:userAdmin", ResponseElementName="checkUserResponse"] [WebMethodDescription="The checkUser method checks if a user " + "or moderator is al

/// moderators in the database.

/// </summary>

/// <remarks>

/// Author: Adrian Turtschi; aturtschi@hotmail.com; Sept 2001

/// </remarks>

[WebServiceAttribute(Description="The userAdmin web service " +

"provides methods to manage users and moderators in the database",Namespace="urn:schemas-syngress-com-soap")]

public class userAdmin : System.Web.Services.WebService {

// SOAP error handling return document structure

/// <value>error document thrown by SOAP exception</value>

public XmlDocument soapErrorDoc;

/// <value>text node with user-friendly error message</value>

public XmlNode xmlFailReasonNode;

}

}

The code for the addUser() method that adds a new user to the database is

shown in Figure 12.22.

20: public void addUser(string userName, string password) {

21: userAdminImplement userAdminObj = new userAdminImplement();

rectly:You need just two lines to add a new user to the system Note two things

in Figure 12.22:

■ First, some decorations were added to the Web method (which

Microsoft calls metadata).They specify the namespaces (lines 14 and 16) and element names (lines 15 and 17) used by the SOAP protocol, as described in Chapter 11.

■ Second, if an exception occurs, you call a custom error handler that returns extended error information as part of a SOAP fault (lines 25 and 26).

Error Handling for the Public Web Methods

If you look at the code that adds users to the system, you’ll see that throwFault

(Figure 12.22, lines 26 and 30) is the name of the method that actually throws a SOAP fault and ends execution of the Web Service method But it does a whole lot more:

■ The (internal) error code is replaced by a user-friendly error message.

■ A log entry is written to the Application event log.

■ The standard SOAP fault XML document is appended with a custom

element, called failReason, where client applications can find the error

message to display to users.

The details of the throwFault method are shown in Figure 12.23.

Figure 12.23 throwFault Method (userAdmin.asmx.cs)

/// <summary>

/// The throwFault method throws a SOAP fault and ends

/// execution of the Web Service method

/// </summary>

/// <param name='message'

/// type='string'

/// desc='start of text node of faultstring element in

/// SOAP fault message'>

/// </param>

For instance, if you try to add a user who is already registered, a SOAP fault

will be returned, as pictured in Figure 12.24.

Figure 12.24 A SOAP Fault Extended by a Custom XML Element

The two other public Web methods of the userAdmin Web Service are very ilar in their structure to the addUser Web method; they are the Web method

sim-addModerator(), which adds a new moderator to the database, and the Web method checkUser(), which checks if a user or moderator is already defined in the database.

Those two methods are presented in Figures 12.25 and 12.26, respectively.

Figure 12.25 addModerator Web Method (userAdmin.asmx.cs)

[WebMethod(Description="The addModerator method adds a new " +

"moderator to the database")]

public void addModerator(

string userName, string password, string newModerator) {

userAdminImplement userAdminObj = new userAdminImplement();

userAdminObj.addModerator(userName, password, newModerator);

/// The checkUser method checks if a user or moderator is

/// already defined in the database

ResponseNamespace="urn:schemas-syngress-com-soap:userAdmin",

ResponseElementName="checkUserResponse")]

[WebMethod(Description="The checkUser method checks if a user " +

"or moderator is already defined in the database")]

public void checkUser(

string userName, string password, bool isModerator) {

userAdminImplement userAdminObj = new userAdminImplement();

Et voilà! You’re done with your first “real”Web Service: the userAdmin Web

Service, which is the user administration module for the Jokes application.

Testing the Public Web Methods

You can immediately check if things work properly by calling it from a Visual Basic script, as described in Chapter 11.The VBS script shown in Figure 12.27 will add a new user.

Figure 12.27 A Simple Visual Basic Script to Test Adding a New User to the Database

myWebService = "http://localhost/Jokes1/userAdmin.asmx"

myMethod = "addUser"

'** create the SOAP envelope with the request

myData = ""

myData = myData & "<?xml version=""1.0"" encoding=""utf-8""?>"

myData = myData & "<soap:Envelope xmlns:soap=""http://schemas."

myData = myData & "xmlsoap.org/soap/envelope/"">"

myData = myData & " <soap:Body>"

myData = myData & " <addUser xmlns=""urn:schemas-syngress-"

myData = myData & "com-soap:userAdmin"">"

myData = myData & " <userName>newUser</userName>"

myData = myData & " <password>newPassword</password>"

myData = myData & " </addUser>"

myData = myData & " </soap:Body>"

myData = myData & "</soap:Envelope>"

msgbox(myData)

set requestHTTP = CreateObject("Microsoft.XMLHTTP")

msgbox("xmlhttp object created")

requestHTTP.open "POST", myWebService, false

requestHTTP.setrequestheader "Content-Type", "text/xml"

requestHTTP.setrequestheader "SOAPAction", myMethod

If things go right, a new user should be added to the database, and a message

box depicting a SOAP return envelope should appear, as shown in Figure 12.28.

Developing the Jokes Service

The second Web Service to develop is the jokes Web Service.The main feature of this Web Service is that it lets registered users retrieve jokes Additionally, it con- tains methods to administer jokes, such as adding and removing jokes, approving jokes submitted by users to be visible to other users, and giving users a way to rate existing jokes In many respects, things are set up in parallel from what you

have already seen in the userAdmin Web Service, which is the Web Service to

manage user information.

Best Practices for Returning Highly Structured Data

Compared with the userAdmin Web Service you have just developed, the jokes

Web Service has one key additional difficulty: how to return joke data.The requirements are as follows:

■ Return anywhere from 1 to 10 jokes.

■ Along with each joke, return its average user rating and the joke fier (for future reference, if for example a user wants to rate that joke).

identi-From the stored procedure sp_getJokes, you can get a SQL record set One

possibility, then, is to simply return the jokes as “record sets” (the correct term

here is objects of type System.Data.DataSet).This magic works because the NET

SOAP serializer, which is the piece of code that puts the data in XML format to

be sent back inside a SOAP return envelope, can indeed serialize that kind of data out of the box However, as we discussed in Chapter 11, returning serialized

DataSets may often not be a good idea because in practice it pretty much forces

your clients to run on a Microsoft NET platform, counter to the idea of Web Services to be an open standard.

Figure 12.28 A Successful Call to Add a New Registered User

adapted to the problem at hand If you want your clients to validate the XML

against a DTD or an XML Schema, you can always pass that information as a

URL (maybe to another Web Service!), but don’t pass that information by default

with every call to the client In your case, you simply pass a structure that looks

essentially like everything above starting from the NewDataSet element; that is,

you want an XML element delineating rows of data, and additional XML

ele-ments delineating the fields of data within each row of data.

This is done very simply by creating a custom C# class, the xmlJokesReturn

class, which is designed to hold a single row of data, as shown in Figure 12.29 Of

course, if you prefer, you could achieve the same thing by using a structure.

Figure 12.29 The xmlJokesReturn Class That Holds the Jokes

/// The xmlJokesReturn class is the return type of all public

/// methods returning joke data

/// </summary>

/// <remarks>

/// Author: Adrian Turtschi; aturtschi@hotmail.com; Sept 2001

/// </remarks>

public class xmlJokesReturn {

/// <value>ID of joke returned</value>

public string jokeID;

/// <value>the actual joke</value>

public string joke;

/// <value>average rating of the joke (can be empty)</value>

public string rating;

/// <summary>

/// Public class constructor

Continued

Because you may return more than one row of data, of course, you can

simply set up the getJokes Web method to return an array of objects of type

xmlJokesReturn.The SOAP serializer does the rest automatically In Figure 12.30,

you can see the definition of the getJokes Web method (note that we haven’t

talked about the corresponding implementation method yet).

Figure 12.30 getJokes Web method (jokes.asmx.cs)

[WebMethod]

public xmlJokesReturn[] getJokes(

string userName, string password, int howMany) {

jokesImplement jokesObj = new jokesImplement();

// error handler omitted

The SOAP object serializer does what it is supposed to do, that is it returns a

serialized array of xmlJokesReturn objects, and you retrieve a SOAP envelope on

the client that may look like the one in Figure 12.31, containing two jokes.

Figure 12.31 SOAP Response Envelope Containing Two Jokes as Serialized

xmlJokesReturn Objects

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

Setting Up Internal Methods to

Wrap the Stored Procedure Calls

Similar to the way you proceeded when developing the userAdmin Web

Service, you want to create internal methods to wrap calls to the stored

dures that interface with the jokes in the database.You have three stored

proce-dures that deal with jokes:

■ sp_manageJoke

■ sp_manageRating

■ sp_returnJokes

The corresponding wrapping methods, part of file JokesImplement.cs, are

shown in detail in Figure 12.32 (createSqlManageJoke), Figure 12.33

(createSqlManageRating), and Figure 12.34 (createSqlReturnJokes).

/// desc='true/false if this is/is not a moderated joke

/// (zero length if N/A)'>

/// desc='the action the SQL stored procedure should take

/// (see the stored procedure definition for allowed action

protected internal void createSqlManageJoke(

string userName, string joke, string isModerated,

string jokeID, string action, SqlCommand sqlCommand) {

/// The createSqlManageRating method sets up the SQL command

/// object for the stored procedure sp_manageRating, which

/// deals with adding and deleting user joke ratings

/// desc='the action the SQL stored procedure should take

/// (see the stored procedure definition for allowed action

/// <returns>the prepared SQL command object</returns>

protected internal void createSqlManageRating(

string jokeID, string rating, string action,

/// desc='true/false if we are interested in (not) moderated

/// jokes (zero length if N/A)'>

/// </param>

/// <param name='returnRandom'

/// type='string'

/// desc='true/false if we are interested getting random jokes

/// (actually, only the starting position is random, from there

/// on we retrieve jokes in sequential order for practical

/// reasons)'>

/// </param>

/// <param name='sqlCommand'

/// type='SqlCommand'

/// desc='a reference to a SQL command object'>

/// </param>

/// <returns>the prepared SQL command object</returns>

protected internal void createSqlReturnJokes(

string howMany, string isModerated, string returnRandom,

}

Setting Up Internal Methods

to Manage Jokes and Ratings

Now that you can call the stored procedures that deal with jokes in the database, you want to implement the business logic that deals with jokes.You have four methods that either add or delete jokes and ratings:

■ addJoke() Checks that user is registered, and then adds the passed joke

as an unmoderated joke to the system.

■ addRating() Checks that user is registered, and then adds the passed rating to the joke having the passed joke identifier to the system.

■ addModerated() Checks that user is a moderator, and then changes the isModerated flag of the joke having the passed joke identifier to the system.

■ deleteUnmoderated() Checks that user is a moderator, and then removes the joke having the passed joke identifier, along with all its user ratings, from the system.

Figure 12.35 shows the business logic for the addJoke method, and

Figures12.36, 12.37, and 12.38 deal with the addRating, addModerated, and

deleteUnmoderated methods, respectively.

Figure 12.35 addJoke Method (JokesImplement.cs)

protected internal bool addJoke(

string userName, string password, string joke) {

string retCode;

try {

// check if user is registered

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

myUser.createSqlCheckUser(userName, password, "", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

protected internal bool addRating(

string userName, string password, int rating, int jokeID) {

string retCode;

try {

// check if user is registered

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

myUser.createSqlCheckUser(userName, password, "", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

// add the joke rating

/// The addModerated method sets a previously submitted joke

/// to become a moderated joke

/// (for moderators only)

/// </summary>

/// <param name='userName'

/// type='string'

/// desc='name of moderator'>

protected internal bool addModerated(

string userName, string password, int jokeID) {

string retCode;

try {

// check if user is a moderator

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

myUser.createSqlCheckUser(

userName, password, "true", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

throw new jokeException(retCode);

/// The deleteUnmoderated method deletes a previously

/// submitted joke (unmoderated) joke

/// (for moderators only)

/// </summary>

/// <param name='userName'

protected internal bool deleteUnmoderated(

string userName, string password, int jokeID) {

string retCode;

try {

// check if user is a moderator

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

myUser.createSqlCheckUser(

userName, password, "true", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

Setting Up Internal Methods to Return Jokes

Finally, you have two methods that return joke data:

■ getJokes() Check that user is registered, and then return one or more moderated jokes, depending on an argument passed

one or more moderated jokes, depending on an argument passed

As mentioned earlier, you should forgo returning DataSets, and return instead

an array of type xmlJokesReturn Figure 12.39 shows the code for the getJokes

method, and Figure 12.40 details the method getUnmoderated.

Figure 12.39 getJokes Method (JokesImplement.cs)

protected internal xmlJokesReturn[] getJokes(

string userName, string password, int howMany) {

string retCode;

try {

// check if user is registered

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

Continued

myUser.createSqlCheckUser(userName, password, "", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

// convert SQL table into xmlJokesReturn class

int rowCount = dataTable.Rows.Count;

xmlJokesReturn[] myJokes = new xmlJokesReturn[rowCount];

for(int i = 0; i < rowCount; i++) {

myJokes[i] = new xmlJokesReturn();

protected internal xmlJokesReturn[] getUnmoderated(

string userName, string password, int howMany) {

string retCode;

try {

// check if user is a moderator

userAdminImplement myUser = new userAdminImplement();

SqlCommand sqlCommand = new SqlCommand();

myUser.createSqlCheckUser(

userName, password, "true", sqlCommand);

databaseAccess myDatabase = new databaseAccess();

SqlDataAdapter sqlDataAdapter = new SqlDataAdapter(sqlCommand);

DataTable dataTable = new DataTable("sqlReturn");

sqlDataAdapter.Fill(dataTable);

// convert SQL table into xmlJokesReturn class

int rowCount = dataTable.Rows.Count;

xmlJokesReturn[] myJokes = new xmlJokesReturn[rowCount];

for(int i = 0; i < rowCount; i++) {

myJokes[i] = new xmlJokesReturn();

Creating the Public Web Methods

You are now finished with the internal methods, and you can now go about implementing the public Web methods for the jokes Web Service Remember

that you put all of those Web methods in the jokes class (the file on the CD is

jokes.asmx.cs) Figures 12.41 through 12.46 detail the code for those public Web methods.

Figure 12.41 addJoke Web Method (jokes.asmx.cs)

[WebMethod(Description="The addJoke method adds a new joke " +

"to the database")]

public void addJoke(

string userName, string password, string joke) {

jokesImplement jokesObj = new jokesImplement();

/// The getJokes method gets howMany (moderated) jokes

/// from the database

[WebMethod(Description="The getJokes method gets <howMany> " +

"(moderated) jokes from the database")]

[return: XmlElementAttribute("jokeData", IsNullable=false)]

public xmlJokesReturn[] getJokes(

string userName, string password, int howMany) {

jokesImplement jokesObj = new jokesImplement();

throwFault("Fault occurred", e.failReason, userName);

return null; // code never reached, but needed by compiler

}

// then, catch general System Exceptions

catch (Exception e) {

throwFault(e.Message, "F_System", userName);

return null; // code never reached, but needed by compiler

}

}

Figure 12.43 addRating Web Method (jokes.asmx.cs)

/// <summary>

/// The addRating method lets a user add a rating

/// for a joke to the database

[WebMethod(Description="The addRating method lets a user add a " +

"rating for a joke to the database")]

public void addRating(

string userName, string password, int rating, int jokeID) {

jokesImplement jokesObj = new jokesImplement();

try {

if((rating < 1) && (rating > 5)) {

throwFault("Fault occurred", "F_ratingInvalid", userName);

/// The getUnmoderated method lets a moderator retrieve

/// howMany unmoderated jokes from the database

[WebMethod(Description="The getUnmoderated method lets a " +

"moderator retrieve <howMany> unmoderated jokes from " +

"the database")]

[return: XmlElementAttribute("jokeData", IsNullable=false)]

public xmlJokesReturn[] getUnmoderated(

string userName, string password, int howMany) {

jokesImplement jokesObj = new jokesImplement();

throwFault("Fault occurred", e.failReason, userName);

return null; // code never reached, but needed by compiler

}

// then, catch general System Exceptions

catch (Exception e) {

throwFault(e.Message, "F_System", userName);

return null; // code never reached, but needed by compiler

Continued

}

Figure 12.45 addModerated Web Method (jokes.asmx.cs)

/// <summary>

/// The addModerated method lets a moderator set a joke to be

/// 'moderated', i.e accessible to regular users

[WebMethod(Description="The addModerated method lets a " +

"moderator set a joke to be 'moderated', i.e accessible " +

"to regular users")]

public void addModerated(

string userName, string password, int jokeID) {

jokesImplement jokesObj = new jokesImplement();