1 an implementation of eide in c#.net mark t. sundsten [email protected]

1

An Implementation of EIDE in C#.NET

Mark T. [email protected]

2

Overview

• Technology Review– HTTP, SOAP, SMXP (all open protocols)– EIDE Functions

• Web Service– What is it?– Web Service Description Language (WSDL)– Web Consumer

• Conceptual Architecture– Web Service, Web Consumer

• Walkthroughs– Building an EIDE Web Service– Building an EIDE Web Consumer

3

Technology Review• HTTP (Hypertext Transport Protocol)

– Underlying communication protocol– Enables a Request/Response architecture– Browser accessing a Web Site is a good example

• SOAP (Simple Object Access Protocol)– Layered on top of HTTP– XML based– Envelope, Header, Body

• SMXP (Simple Message eXchange Protocol)– Leverages SOAP– The idea is that I am invoking a function on a remote machine rather than sending a

message.– Data is communicated via parameters and return values

• EIDE Functions– logical functions defined to facilitate the exchanging of meter, power system and schedule

data.– Examples include PutSchedule, PutScheduleAck, GetSchedule, PutMeter, etc– The EIDE Communications Protocol Document defines these functions in terms of the

above open technologies (HTTP, SOAP, SMXP).

EIDE Functions

SMXP

SOAP

HTTP

4

Web Service• An application component accessible via

open protocols (like HTTP, XML, SMXP, SOAP)

• Processes XML messages framed using SOAP

• Describes its message using XML Schema (XSD)

• Interface is fully described using WSDL (Web Service Description Language) Web Service

SMXP

SOAP

HTTP

5

WSDL (Web Service Description Language)

– Standard (developed by W3C -- Ariba, IBM, Microsoft)

– Machine consumable format (XML)

– Describes details of how to access (required inputs, message format, etc. )

– Describes where to access (target URL, ports, etc.)

– Contains a Schema Definition (XSD)

6

Web Consumer

• A Web Consumer is any application that accesses a web service

7

Secure transmittal of XML document over Internet (HTTPS/SOAP/X.509 certificates)

HTTP Request

HTTP Response

Web Consumer

Conceptual Architecture

Web ServiceWeb Consumer

De-Serialize from XMLSerialize to XML

Application Objects

Data

Data

Data

ApplicationObjects

Data

Data

Data

• Start with the concept of an application consuming a web service.

Entity A Entity B

8

Secure transmittal of XML document over Internet (HTTPS/SOAP/X.509 certificates)

GetSchedule

GetScheduleResponse

Conceptual Architecture

EIDE Web ServiceEIDE Web Consumer

De-Serialize from XMLSerialize to XML

EIDE Objects

MeterData

Pwr SysData

Schedules

RDBMSCSV files

EIDE Objects

MeterData

Pwr SysData

Schedules

RDBMS

• Specifically, an EIDE application consuming an EIDE web service.

Entity A Entity B

9

Conceptual Architecture• EIDE specifies that an entity can be a

consumer, a service, or both. (An entity may send or receive unsolicited messages).

GetSchedule

GetScheduleResponse

EIDE Web Service

RDBMS

EIDE Web Consumer

EIDE Objects

RDBMS

GetScheduleAsyncReply

GetScheduleAsyncReplyResponse

EIDE Web Consumer

RDBMS

EIDE Web Service

RDBMS

EIDE Objects

EIDE Objects

EIDE Objects

Entity A Entity B

10

F i r e w

a l l

Conceptual Architecture• Finally, Integrate with

Scheduling/EMS Systems

GetSchedule

GetScheduleResponse

EIDE Web Service

RDBMS

EIDE Web Consumer

EIDE Objects

RDBMS

GetScheduleAsyncReply

GetScheduleAsyncReplyResponse

EIDE Web Consumer

RDBMS

EIDE Web Service

RDBMS

EIDE Objects

EIDE Objects

EIDE Objects

Scheduling S

ystem/

EM

S S

ystem

Scheduling S

ystem/

EM

S S

ystem

Entity A Entity B

F i r e w

a l l

11

Underlying technologiesLeverage

• Microsoft IIS– For Listening– Authentication, encryption

• Microsoft .NET Framework– Serialize/De-serialize XML to/from application objects

• ADO.NET– For Mapping application objects to/from the RDBMS.

12

Build An EIDE Web Service

• Before you get started, you will need the following products:– Microsoft Visual Studio.NET

• This is the Integrated Development Environment (IDE) for editing and compiling your C# code.

– Microsoft .NET Framework • Distributed with newer versions of the OS, available off the

WEB.

• Microsoft Internet Information Server (IIS).• Oracle (this walkthrough utilizes Oracle, but you could use

SQL Server or Microsoft Access)

13

1. Start with the EIDE schema (eide.xsd).


14

2. Use Microsoft’s XSD utility to generate C# classes that map to the schema (eide.cs).


15


3. Start the Microsoft Development Environment.

16


4. Load a C# Web Service template

• From the IDE, Select FileNewProject to bring up the New project dialog

• Select the project type, C# project

• Select the template, ASP.Net Web Service

• Change the location from http://localhost/WebService1 to http://localhost/EIDEServer

• Click the OK button

http://localhost/WebService1

http://localhost/WebService1

http://localhost/EIDEServer

http://localhost/EIDEServer

17


5. Alter to use meaningful names.

• In the solution explorer, rename Service1.asmx to EIDEService.asmx

• Right Click on design area and select view code.

• In the source code, change the namespace, Class Name, and method name from Service1 to EIDEService

18

Build An EIDE Web Service6. Add the eide definitions

(eide.cs) to your C# project.• Right click on the EIDEService

project in the solution explorer and select “Add Add Class”

• For a name, type in eide.cs. Click “Open”

• Select the entire contents of the file and replace with the eide.cs that you created earlier using the xsd utility.

• (A shortcut to the three steps above is to drag the eide.cs file from its folder and drop it on top of the EIDE Service project in the solution explorer).

19


7. Define the EIDE Web Method, PutPID• View the EIDEService source code by clicking on the

EIDEService.asmx.cs tab)• Scroll to the bottom and observe the commented out sample web

method.

20


7. Define the EIDE Web Method, PutPID (cont).• Uncomment the entire web method and replace the return type

string with a return type of PutPIDResponse• Change the method name from HelloWorld() to PutPID()• Add two parameter definitions within the parenthesis separated

by a comma: MessageInfoType MessageInfo, PIDType PID• Instead of returning “Hello World” return null

21


8. Compile and deploy (locally) your stubbed out Web Method.

• Type Ctrl-Shift-B

22

Build An EIDE Web Service9. Note: You now have now built an

accessible web service that other programmers can consume and test against. To illustrate this:

• Bring up a browser and point it to the following url to see a listing of your Web Methods (you only have one at this point). http://localhost/EIDEService/EIDEService.asmx

• Click on the ServiceDescription to see the automatically generated WSDL. The WSDL contains the complete specifications for communicating with your Web Service.

http://localhost/EIDEService/EIDEService.asmx

http://localhost/EIDEService/EIDEService.asmx

23


9. (Continued)

• Click on the PutPID to see examples of the http request that your program expects to receive and the http response that it will return.

24

Build An EIDE Web Service10 Design and build a RDBMS table to

store the data when it comes in. (This example uses Oracle, although you could just as easily use MS Access or SQL Server.) For purposes of this walkthrough, I am only dealing with the MessageInfo portion of the EIDE data. It is left as an exercise to create tables for storing everything else. The following can be used to create the table in Oracle.

create table eide_MessageInfo ( SysGenID Number(10) default 0 NOT NULL ,Timestamp Date NOT NULL ,Sender VARCHAR(40) ,Receiver VARCHAR(40) ,EntityCode VARCHAR(40) ,ProcessID Number(10) default 0 NOT NULL ,DataSet Number(10) default 0 NOT NULL ,ListID Number(10) default 0 NOT NULL ,ResponseSysGenID Number(10) default 0 NOT NULL ,Comments VARCHAR(200) ,AsyncReplyFlag Number(10) default 0 NOT NULL );CREATE INDEX eide_MessageInfo$PK ON

eide_MessageInfo (SysGenID, Timestamp, Sender);

25


11. Setup the ADO.Net C# Data Adapter necessary to access your newly built table.

• Return to the Microsoft IDE

• Select the EIDEService.asmx [Design] tab

• From the View pull down menu select Toolbox

26


11. (Continued)• Drag an OracleDataAdapter from the toolkit on to your

design surface. This will bring up the Data Adapter Configuration Wizard. Click Next

• Click New Connection• Enter the Oracle service name, username, and password for

accessing your Oracle database. Click OK.

27


11. (Continued)• You will be returned to the Data Adapter Configuration

Wizard. Click Next to continue.• When prompted for a Query type, take the default and click

Next• When prompted to Generate the SQL statements, click the

Query Builder button.• On the Add Table dialog, select eide_MessageInfo and click

Add, then Close.

28


11. (Continued)• On the Query Builder dialog, click “*” to select all columns,

then click the OK button.• On the Data Adapter Configuration Wizard dialog, click

Finish.

29

Build An EIDE Web Service11. (Continued)

• You have now created two ADO.NET constructs (and all of the C# code behind them): OracleDataAdapter1, and OracleConnection1. These objects understand the specifics of accessing your particular RDBMS software.

• Give the Data Adapter a reasonable name by right clicking on OracleDataAdapter1 and selecting Properties. Then change the Name Property to oracleDataAdapterMessageInfo

30


12. Setup the ADO.NET C# Dataset necessary to access your newly built table.

• Right Click on the EIDEService project in the Solution Explorer and select AddAdd New Item.

• In the Add New Item dialog select the Dataset template and change the name to eide_MessageInfo.xsd. Click the Open button.

31


13. This will bring you to the Dataset Design editor.

• Build an Element that matches your table by Dragging the E symbol onto the designer. Fill it out as shown.

32


14. (Continued)• You have now created all of the ADO.NET C# constructs

necessary to access your database table.• DataAdapter – Handles specifics of accessing data in

your table• DataSet -- A logical view of your table. • DataConnection – Manages connecting to your

database.

33


15. Put some meat in your web method• Navigate your way back to your stubbed out web method (click

on the EIDEService.asmx.cs tab and scroll down to the bottom.)• Add the code below to initialize your dataset. (This is a logical in

memory version of your table.)

//// Instantiate MessageInfo dataset.//eide_MessageInfo datasetMessageInfo = new eide_MessageInfo();oracleDataAdapterMessageInfo.Fill(datasetMessageInfo, "tblMessageInfo");

34


15. (Continued)• Add code to insert the EIDE MessageInfo data into the dataset.

// // Insert the MessageInfo into the dataset.//datasetMessageInfo.tblMessageInfo.AddtblMessageInfoRow(

MessageInfo.SysGenID,MessageInfo.TimeStamp,MessageInfo.Sender,MessageInfo.Receiver,MessageInfo.EntityCode,MessageInfo.ProcessID,MessageInfo.DataSet,MessageInfo.ListID,MessageInfo.ResponseSysGenID,MessageInfo.Comment,0,MessageInfo.UserID,0

);

35


15. (Continued)• add code to save the data.

// Save the DataOracleDataAdapterMessageInfo.Update(dsMessageInfo, "tblMessageInfo");

36


15. (Continued)• Finally, rather than returning null, add code to build the

PutPIDReturn structure and return it.

// Build and return appropriate response

PutPIDResponse resp = new PutPIDResponse();resp.ReplyBlock = new ReplyBlock();resp.ReplyBlock.Reply = new ReplyType();resp.ReplyBlock.Reply.ReplyCode = ReplyTypeReplyCode.processedOK;resp.ReplyBlock.Reply.ReplyText = "Message Info Successfully Saved."return resp;

37

Build An EIDE Web Service16. OK! You are

done. You have built a fully functional Web Service, capable of receiving XML over the internet, converting the XML to application data and saving it into a RDBMS. This is the only code you actually had to write.

// Web Service method supporting EIDE PutPID function.[WebMethod]public PutPIDResponse PutPID(

MessageInfoType MessageInfo,PIDType PID)

{

// Instantiate MessageInfo dataset.

eide_MessageInfo datasetMessageInfo = new eide_MessageInfo();OracleDataAdapterMessageInfo.Fill(datasetMessageInfo, "tblMessageInfo");

// Insert the MessageInfo into the dataset.

datasetMessageInfo.tblMessageInfo.AddtblMessageInfoRow(MessageInfo.SysGenID,MessageInfo.TimeStamp,MessageInfo.Sender,MessageInfo.Receiver,MessageInfo.EntityCode,MessageInfo.ProcessID,MessageInfo.DataSet,MessageInfo.ListID,MessageInfo.ResponseSysGenID,MessageInfo.Comment,0,MessageInfo.UserID,0);

// Save the Data

OracleDataAdapterMessageInfo.Update(datasetMessageInfo, "tblMessageInfo");

// Build and return appropriate response

PutPIDResponse resp = new PutPIDResponse();resp.ReplyBlock = new ReplyBlock();resp.ReplyBlock.Reply = new ReplyType();resp.ReplyBlock.Reply.ReplyCode = ReplyTypeReplyCode.processedOK;resp.ReplyBlock.Reply.ReplyText = "Message Info Successfully Saved."return resp;

}

38

Build an EIDE Web Consumer

1. Start the Microsoft Development Environment.

39


2. Load a C# Console App template

• From the IDE, Select FileNewBlank Solution to bring up the New project dialog

• Select the project type, C# project

• Select the template, Console Application

• Change the name from ConsoleApplication1 to EIDEConsumer

• Click the OK button

40


3. Alter to use meaningful names.• In the source code, change the Class name, to EIDEConsumer

41

4. Add the C# EIDE definitions to your new C# project by querying the EIDE Web Service’s WSDL.

• Right click on References in the solution explorer and select Add Web Reference

• In the Add Web Reference dialog, type in a location of http://localhost/EIDEService/EIDEService.asmx

• Click the Add Reference button.


42


5. Add using clauses at the top of your C# code. This allows us to avoid referencing the namespaces every time we access classes within.

using EideConsumer.localhost;using System.Security.Cryptography.X509Certificates;

43

Build an EIDE Web Consumer6. Build an EIDE

MessageInfo structure with the following C# code in the body of your main() method

// Instantiate an EIDE MessageInfo object

MessageInfoType info = new MessageInfoType();info.SysGenID = 1;info.TimeStamp = DateTime.Now;info.Sender = "Entity A";info.Receiver = "Entity B";info.EntityCode = "ENTA";info.ProcessID = 2;info.DataSet = 3;info.ListID = 4;info.ProcessIDSpecified = true;info.ListIDSpecified = true;info.DataSetSpecified = true;

44

Build an EIDE Web Consumer7. Build an EIDE PIDType

structure with the following C# code in the body of your main() method

// Instantiate an EIDE PID Object.

PIDType pid = new PIDType();pid.NumberofAccounts = 1;pid.InitialHourEnding = new DateTime(2004,3,22,5,0,0);pid.Accounts = new PIDTypeAccountsAccount[1];pid.Accounts[0] = new PIDTypeAccountsAccount();pid.Accounts[0].PidDescription = new PIDDescriptionType();pid.Accounts[0].PidDescription.AccountCode = "AA";pid.Accounts[0].PidDescription.StartTime = DateTime.Now;pid.Accounts[0].PidDescription.EndTime = DateTime.Now.AddHours(1);

45


8. Set up for the Web Service call by adding the following code:

// Set up for the web service call.

EIDEService service = new EIDEService();

46


9. Secure your Web Service Call using a X.509 compliant certificate with the following 2 lines of C# code:

// Set up client certificate for communications with EIDE server.X509Certificate certificate = X509Certificate.CreateFromCertFile(@"c:\eide\mts.cer");service.ClientCertificates.Add(certificate);

47


10.Add two more lines of C# code to make the Web Service call.

// Call the EIDE PutPID Method

PutPIDResponse ret;ret = service.PutPID(info, pid);

48


11. Finally, add some code that inspects the reply text generated by the Web Service.

// Display the responseConsole.WriteLine(ret.ReplyBlock.Reply.ReplyText);

49


12. Now hit CTRL-F5 to compile and run your Web Consumer.

• If all went well, you should see the message “Message Info Successfully Saved.” returned from the Web Service call.

• You should also verify that the Web service stored the data that your web consumer sent to it.

50


Done! You have successfully built a Web Service that offers the EIDE PutPID functionality, and a Web Consumer that utilizes it!

51

HTTP Request that was sent over the wire by your Web Consumer.

POST /EIDEService/EIDEService.asmx HTTP/1.1User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 1.1.4322.573)Content-Type: text/xml; charset=utf-8SOAPAction: "http://EntityA.com/EIDE/PutPID"Content-Length: 1240Expect: 100-continueConnection: Keep-AliveHost: localhost:8080

<?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"> <soap:Body> <PutPID xmlns="http://EntityA.com/EIDE/"> <MessageInfo> <SysGenID xmlns="http://www.nwpp.org/eide">1</SysGenID> <TimeStamp xmlns="http://www.nwpp.org/eide">2004-10-29T13:46:11.6940256-07:00</TimeStamp> <Sender xmlns="http://www.nwpp.org/eide">Entity A</Sender> <Receiver xmlns="http://www.nwpp.org/eide">Entity B</Receiver> <EntityCode xmlns="http://www.nwpp.org/eide">ENTA</EntityCode> <ProcessID xmlns="http://www.nwpp.org/eide">2</ProcessID> <DataSet xmlns="http://www.nwpp.org/eide">3</DataSet> <ListID xmlns="http://www.nwpp.org/eide">4</ListID> </MessageInfo> <PID> <InitialHourEnding xmlns="http://www.nwpp.org/eide">2004-03-22T05:00:00.0000000-08:00</InitialHourEnding> <NumberofAccounts xmlns="http://www.nwpp.org/eide">1</NumberofAccounts> <Accounts xmlns="http://www.nwpp.org/eide"> <Account> <PidDescription> <StartTime>2004-10-29T13:46:11.6940256-07:00</StartTime> <EndTime>2004-10-29T14:46:11.6940256-07:00</EndTime> <AccountCode>AA</AccountCode> </PidDescription> </Account> </Accounts> </PID> </PutPID> </soap:Body></soap:Envelope>

52

HTTP Response that was received from your Web Service.HTTP/1.1 100 ContinueServer: Microsoft-IIS/5.1Date: Fri, 29 Oct 2004 20:46:12 GMTX-Powered-By: ASP.NET

HTTP/1.1 200 OKServer: Microsoft-IIS/5.1Date: Fri, 29 Oct 2004 20:46:13 GMTX-Powered-By: ASP.NETX-AspNet-Version: 1.1.4322Cache-Control: private, max-age=0Content-Type: text/xml; charset=utf-8Content-Length: 503

<?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"> <soap:Body> <PutPIDResponse xmlns="http://EntityA.com/EIDE/"> <PutPIDResult xmlns="http://www.nwpp.org/eide"> <ReplyBlock> <Reply> <ReplyCode>processedOK</ReplyCode> <ReplyText>Message Info Successfully Saved.</ReplyText> </Reply> </ReplyBlock> </PutPIDResult> </PutPIDResponse> </soap:Body></soap:Envelope>

53

Questions?, Need help?

Send me an e-mail at [email protected]

1 an implementation of eide in c#.net mark t. sundsten [email protected]

Documents

eide web service slide

eide web consumer slide

aspnet web service

eide application

web site

eide schema

c web service template

implementation of eide