6.2 X-tee andmeteenuse ja kliendi loomine WSDL baasil (.NET platvormil).

Keskkond: Windows OP, .NET framework(3.5+), IIS(7+)

https://www.microsoft.com/en-us/download/search.aspx?q=.net%20framework

Tööriistad: MS Visual Studio (2010+) Professional/Ultimate/..,

https://www.visualstudio.com/post-download-vs/?sku=pro&clcid=0x409&telem=ga

SoapUI https://www.soapui.org/downloads/soapui.html

Raamistikud: WCF

Meetod: “Top Down“  -  olemasoleva WSDL baasil genereerime C# koodi.

6.2.1        Ettevalmistused

Rakenduse töökeskkonna ettevalmistamine – Internet Infomation Services (IIS[1]).

Kõigepealt tuleb kontrollida, kas kõik vajalikud Windowsi komponendid on aktiveeritud. Vastasel juhul tuleb paigutada/lisada puuduvad komponendid. Ava kasutades Control Panel'it Programs and Features ja vali Turn Windows features on or off.

Lülita sisse järgmised komponendid:

  • Common HTTP Features
    • Directory Browsing and Static Content

Kuna liidestuskomponendi arendus käib „Top Down“ meetodi järgi, siis peab serveril publitseerima andmeteenuse WSDL faili. Selle komponendi lisamisega lubame turvaserverile ligipääsu staatilistele failidele. Seda kasutavad nii teenuse kasutajad kui ka turvaserveri administraatorid.

  • Application Development Features
    • .NET Extensibility
    •  ASP.NET
X-Tee turvaserverid ei edasta SOAPAction päist. Sellepärast peab eeldama, et liidestuskomponendid haldavad sissetulevaid SOAP sõnumeid body alamelemendi järgi. WCF raamistikus on vaja lisada laiendus, mis võimaldab sama käitumist, vaikimisi kasutatakse SOAPAction päist. Selle probleemi lahenduse kirjeldus tuleb hiljem.

  • .NET Framework Advanced Services
    • ASP.NET
    • WCF Services
    • HTTP Activation

Märkus! WCF või ASP.NET teenused võivad genereerida WSDL faili automaatselt,kui teha päring aadressile 
http://localhost:port/teenusenimi?wsdl.
Aga automaatselt genereeritud failidel puuduvad kohustuslikud X-tee nimeruumi elemendid. Sellepärast peab publitseerima algse teenusekirjelduse faili, mida kasutati koodi genereerimiseks.

 

Eelnevalt kirjeldatud sammude realiseerimiseks võib kasutada ka järgnevat konsoolikäsku, et paigaldada kõik vajalikud komponendid:

start
  /w pkgmgr /iu:IIS-WebServerRole;IIS-WebServer;IIS-CommonHttpFeatures;IIS-StaticContent;IIS-DefaultDocument;IIS-DirectoryBrowsing;IIS-HttpErrors;IIS-HttpRedirect;IIS-ApplicationDevelopment;IIS-ASPNET;IIS-NetFxExtensibility;IIS-ASP;IIS-CGI;IIS-ISAPIExtensions;IIS-ISAPIFilter;IIS-ServerSideIncludes;IIS-HealthAndDiagnostics;IIS-HttpLogging;IIS-LoggingLibraries;IIS-RequestMonitor;IIS-HttpTracing;IIS-CustomLogging;IIS-ODBCLogging;IIS-Security;IIS-BasicAuthentication;IIS-WindowsAuthentication;IIS-DigestAuthentication;IIS-ClientCertificateMappingAuthentication;IIS-IISCertificateMappingAuthentication;IIS-URLAuthorization;IIS-RequestFiltering;IIS-IPSecurity;IIS-Performance;IIS-HttpCompressionStatic;IIS-HttpCompressionDynamic;IIS-WebServerManagementTools;IIS-ManagementConsole;IIS-ManagementScriptingTools;IIS-ManagementService;IIS-IIS6ManagementCompatibility;IIS-Metabase;IIS-WMICompatibility;IIS-LegacyScripts;IIS-LegacySnapIn;IIS-FTPPublishingService;IIS-FTPServer;IIS-FTPManagement;WAS-WindowsActivationService;WAS-ProcessModel;WAS-NetFxEnvironment;WAS-ConfigurationAPI


6.2.2        X-tee andmeteenuse loomine

Eeldus: persons_register.wsdl teenuse kirjelduse fail on valmis ning on alla laetud WcfExtensions.dll (või selle lähtekood githubist[3] )

6.2.3        Rakenduse ettevalmistamine

Tekitame tööruumi Visual Studio's, kus hakkame rakendust tegema. Esimene rakendus on teenuseosutaja liidestuskomponent ehk Producer, milleks kasutame WCF Service Application malli.

Loome uue projekti ja valime vajaliku malli:

Kustutame:

  • IService1.cs,
  • Service1.svc
  • Service1.svc.cs

failid selleks, et meil oleks puhas rakendus. Ja lisame vajalikud failid. Teenuse kirjelduse faili jaoks võiks luua kataloogi nimega „wsdl“ ja lisada sinna  varem ettevalmistatud WSDL faili.

 Loome kataloogi:


Vali  projekt Producer ja kutsu välja kontekstmenüü, kus tuleb valida Add-> New Folder -> kausta nimi: wsdl

Lisame laienduse faili:

Vali projekt Producer ja kutsu välja kontekstmenüü, kus tuleb valida Add->Existing item-> WSDL fail.

Lisa viide .dll failile:

References -> Kontekstmenüüs Add reference -> Avatud aknas Reference Manager tuleb valida Assemblies -> Browse -> vali  WcfExtensions.dll faili.


Märkus! Et lisatud faili IIS publitseerimise ajal mitte  kaotada, tuleb selle faili omadusi muuta järgnevalt: 
Build Action -> Content
Copy to Output Directory -> Copy always


Nüüd, kui kõik vajalikud komponendid on rakenduses olemas, saab alustada koodi kirjutamisega. Kõigepealt on vaja luua teenuse liidese ja andmemudeli klassid. Selle tegemiseks on mitu varianti:

1.       Kasutada käsurealt programmi svcutil.exe[4] ja sellega loodud failid lisa rakendusele. Kui on vaja liidese koodi muuta, siis tuleb seda operatsiooni korrata.

2.       Käsurealt tuleb käivitada järgmine käsk:

svcutil  /l:cs /o:IPersonService.cs /noConfig person_register.wsdl

/l: - Keel, vaikimisi on CSharp

/o: - tulemuse faili nimi, vaikimisi on WSDL faili nimi

/noConfig - Konfiguratsioonifaili ei ole vaja

Viimane parameeter on WSDL faili nimi

Lisa tulemus projekti kausta

3.       Kasutada Visual Studio’s kasutajaliidest (mis omakorda kasutab svcutil.exe).

  • Kliki projekti alamkataloogi References nuppu
  • Kontekstmenüüst valime  Add service reference.
  • Väljale Address paneme teenuse kirjelduse faili nime koos kataloogi nimega

nt: F:\Workspace\NET\XRoad\Samples\Producer\wsdl\person_register.wsdl

  • Väljale Namespace tuleb mingi mõistlik nimetus teenuse objektide nimeruumile.

nt: pplService

  • Kliki Advanced nuppu
  • Kontrolli, et Allow generation of asynchronous operations märkeruudul ei ole linnukest pandud (X-tee ei toeta asünkroonseid meetodeid)
  • Pane linnuke Always generate message contracts märkeruudule
  • Kliki OK

Selle sammu tulemusel peaks tekkima pplService  kaust Service Reference kataloogi alla.

 

Märkus!
  Tulevikus, kui WSDL fail on muudetud ja andmetüüpe on vaja samuti uuendada,
  tuleb rakenduses valida Service Reference kataloogist pplService
  ja kontekstmenüüst Configure Service Reference ... ja valida  OK.
 Sellega käivitatakse svcutil.exe  programm ja kood luuakse nullist.

 

Sel viisil lisatakse rakendusele teenuse kliendi kood ja mistõttu ka teenuse klientrakenduse loomisel on esimesed sammud samasugused. 

Miks seda teenuse osutajal tarvis on? Sest luuakse teenuse liides ja teenuses kasutatavate objektide klassid.

 

Object Browser’ist saab vaadata loodud objekte:

  1. Teenuse osutaja liides
  2. Teenuse kasutaja klass
  3. Teenuses olevaid objektid
  4. Teenuse päringu ja X-tee sõnumite päiste objektid.

Märkus!
  Peale teenuse viite lisamist tekkib Web.conf failis element <client>.
  Kuna teenuse osutaja seda ei kasuta, siis võib selle eemaldada.
 
<configuration>

  <system.serviceModel>
    …
    <client>
      <endpoint address="http://localhost:8080/person_register/services/person_registerSOAP"
        binding="basicHttpBinding" bindingConfiguration="person_registerSOAP"
        contract="pplService.person_register" name="person_registerSOAP" />
    </client>

 

6.2.4        Teenuse implementeerimine

Lisame teenuse liidest realiseeriva faili:

Rakenduse kontekstmenüüs valige „Add“ -> „New Item ...“ -> „WCF Service“ -> PeopleRegister.svc (IPeopleRegister.cs faili ei ole vaja ja selle võib ära kustutada).

using System;
using Producer.pplService;
 
namespace Producer
{
    public class PeopleRegister : pplService.person_register
    {
        public personListResponse personList(personListRequest1 request)
        {
            throw new NotImplementedException();
        }
    }
}


Lisame personList’le lihtsama realisatsiooni, kus kopeeritakse päised ja tagastatakse staatiline vastus:

public personListResponse personList(personListRequest1 request)
{
    return new personListResponse
    {
        client = request.client,
        service = request.service,
        id = request.id,
        protocolVersion = request.protocolVersion,
        userId = request.userId,
        response = new personListResponseResponse
        {
            person = new person
            {
                birthDate = DateTime.Now,
                firstName = "Juhan",
                lastName = "Tamm",
                personContact = new contact{
                    address = "Metsa 12",
                    email = new []{
                        "juhan@ee.ee"
                    },
                    phone = new []{
                        "333333"
                    }
                }
            }
        }
    };


Teenus suudab tagastada mingi lihtsama staatilise vastuse ja WCF sõnumite haldamise meetodi muutmiseks lisame teenust realiseerivale klassile DispatchByBodyElementBehavior atribuudi, mis võimaldab registreerida operatsioonid päringu halduri listis. Iga operatsioon tuleb eraldi märkida atribuudiga DispatchBodyElement, millel on kaks argumenti:

personList – SOAP sõnumi juurelemendi nimi (teenuse operatsiooni nimi)

http://persons_register.x-road.ee – teenuse osutaja nimeruum (sama nagu WSDL faili sees).

 

[DispatchByBodyElementBehavior]
public class PeopleRegister : pplService.person_register
{
    [DispatchBodyElement("personList", "http://persons_register.x-road.ee")]
    public personListResponse personList(personListRequest1 request)
    {
        ...
    }
}


Lisaks tuleb Web.Confi failis registreerida WCF laiendus. Konfiguratsioonifaili muutmiseks on võimalik kasutada Visual Studios integreeritud liidest Microsoft Service Configuration Editor. Vali fail Web.config ja kontekstmenüüst Edit WCF Configuration.

Märkus! Enne Type Browseri kasutamist tuleb rakendus kompileerida. Type Browser parsib kompileeritud failid, et leida üles tüüpide klassid. Sellepärast võivad värskelt loodud klassid sealt puududa.

1.Registreeri uus laiendus

a. Vali Advanced -> Extensions -> behavior element extensions -> New ...

b. Veergu Name: CustomMessageFilter.

c.  Veeru Type sisse tuleb valida EndpointBehaviorExtension tüüp, mis asub WcfExtensions.dll’sees

2. Loo uus teenuse Endpoint Behaviour kasutades registreeritud laiendust

a. Vali Advanced -> Endpoint Behaviors -> New Endpoint Behavoir Configuration

b. Name: CustomMessageFilterBehavior

c. Alas Behavior element extension position kliki Add ...

d.  Lisa CustomMessageFilter element.

3. Registreeri teenuse endpoint

a. Service -> Create a New service

b. Service type – kliki  Browse … ja vali Producer.PeopleRegister tüüp Producer.dll’ist

c. Next

d. Contract väli peab olema automaatselt täidetud.

e. Next

f.  Vali New binding configuration

g.  Communication mode : HTTP

h. Method of interopability : Basic Web Services interopability

i.  Jäta väli Address tühjaks

j.  Finish

4. Määra varem loodud Endpoint Behaviour uuele teenuse endpointle.

a. Service -> Producer.PeopleRegister -> Endpoints -> (Empty Name)

b. BehaviorConfiguration: CustomMessageFilterBehavior

5. Salvesta seadistused

a.  File -> Save

Peale neid samme peab Web.config failis olema järgmine element:

  <system.serviceModel>
    <services>
      <service name="Producer.PeopleRegister">
        <endpoint address="" behaviorConfiguration="CustomMessageFilterBehavior"
          binding="basicHttpBinding" bindingConfiguration="" contract="pplService.person_register" />
      </service>
    </services>
    <extensions>
      <behaviorExtensions>
        <add name="CustomMessageFilter" type="WCFExtensions.Helpers.Filters.FilteringEndpointBehaviorExtension, WcfExtensions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      </behaviorExtensions>
    </extensions>
    <bindings>
      <basicHttpBinding>
        <binding name="person_registerSOAP" />
      </basicHttpBinding>
    </bindings>
    <behaviors>
      <endpointBehaviors>
        <behavior name="CustomMessageFilterBehavior">
          <CustomMessageFilter />
        </behavior>
      </endpointBehaviors>
      <serviceBehaviors>
        <behavior name="">
          <serviceMetadata httpGetEnabled="true" httpsGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="true" />
        </behavior>
      </serviceBehaviors>
    </behaviors>
    <protocolMapping>
        <add binding="basicHttpsBinding" scheme="https" />
    </protocolMapping>   
    <serviceHostingEnvironment aspNetCompatibilityEnabled="true" multipleSiteBindingsEnabled="true" />
  </system.serviceModel>


Andmeteenus on valmis. Peale rakenduse käivitumist peab avanema järgmine vaade:

6.2.5   Publitseeri teenus IIS serveril

Enne teenuse kasutamist tuleb see IIS serverile paigutada:

Märkus! Et rakendus edukalt IIS serveril publitseerida,
  tuleb see administraatori õigustes kasutajana käivitada. 

 

1. Kompileeri rakendus

a. Vali rakenduse fail ja kontekstmenüüst kliki Publish. Tekib Publish Web aken.

b. Vali Custom ja anna profiilile nimi.

c. Publish method: File System

d. Target location: IIS rakenduse kaustas loo uus kataloog ja vali see

nt: C:\inetpub\wwwroot\persons

e. Next

f.  Configuration: Release

g. Next -> Publish

2.  Loo uus katalog IIS serveri peal.

a. Tee lahti IIS Manager

b. Vali Sites kontekstmenüüst Add Website. Tekib uus aken, kus tuleb sisestada kataloogi konfiguratsioon

c. Sitename: persons

d. Application Pool: vali pool millel .NET raamistiku versioon on sama/uuem kui rakenduse target raamistik.

e. Physical path: punktis 1.d valitud kaust

f.  IP address: lokaalse masina IP-aadress

g. OK

Peale neid samme peaks teenus olema kättesaadav lokaalse masina IIS serverist. (nt: http://172.25.200.47/PeopleRegister.svc)

6.2.6  X-tee klientrakenduse loomine

Lisage eksisteeriva solution’i alla uus rakendus, millega hakkame teenust kasutama (näiteks kasutades Console Application malli). Esimesena tuleb lisada viide meie teenusele ja genereerida kliendi kood ja andmemudeli objektid. On mitu variandi, kuidas seda teha:

  1. Kasuta käsurealt programmi svcutil.exe ja selle tulemuse failid lisa rakendusele. Kui on vaja liidese koodi muuta, siis tuleb seda operatsiooni uuesti teha.

a. Käsurealt tuleb käivitada järgmine käsk:

svcutil /l:cs /o:IPersonService.cs /noConfig person_register.wsdl

/l: - Keel, vaikimisi on Csharp

/o: - tulemuse faili nimi, vaikimisi on WSDL faili nimi

/noConfig - Konfiguratsioonifaili ei ole vaja Viimane parameeter on WSDL faili nimi

2. Kasutada Visual Studio kasutajaliidest.

a. Kliki projekti alamkataloogi References nuppu

b. Kontekstmenüüst vali Add service reference.

c.  Väljale Address pane teenuse kirjelduse faili URL lokaalsest masinast

nt: http://172.25.200.47/wsdl/person_register.wsdl

Märkus! Praegu võtame otse ühendust meie lokaalse teenuse osutajaga. Tavaliselt tuleb liidestuskomponendi loomisel kasutada andmeteenuse kirjelduse faili turvaserverist.

d.  Välja Namespace sisse tuleb mingi mõistlik nimetus teenuse objektide nimeruumile.

nt: pplService

e. Kliki Advanced nuppu

f.  Kontrolli, et veerus Allow generation of asynchronous operations märkeruudul ei ole linnukest

g.  Pane linnuke Always generate message contracts märkeruudule

h. Kliki OK

Nüüd on võimalik luua kliendi objekt ja kutsuda välja teenuse meetodid. Kasutame järgmisi parameetreid, et teenust välja kutsuda:

  1. Service/xRoadInstance: ee-dev (tegutseme X-tee arenduskeskkonnas)
  2. Service/ memberClass: COM
  3. Service/ memberCode: <XRD_MEMBER>
  4. Service/ subsystemCode: <TRAINING_PROVIDER_XX>
  5. Service/ serviceCode: <andmeteenuse nimetus>
  6. Service/ serviceVersion: <andmeteenuse versiooni nr>
  7. protocolVersion: 4.0
  8. client /xRoadInstance: ee-dev (tegutseme X-tee arendusekeskkonnas)
  9. client / memberClass: COM
  10. client / memberCode: <XRD_MEMBER>
  11. client / subsystemCode: <TRAINING_CONSUMER_XX>

class Program{

    static void Main(string[] args) {

        //Create header objects

        var protocolVersion = "4.0";

        var id = Guid.NewGuid().ToString();

        var userId = "EE37007160274";

        var service = new XRoadServiceIdentifierType {

            xRoadInstance = "ee-dev",

            memberClass = "COM",

            memberCode = "11333578",

            subsystemCode = "aktorstest-db01",

            serviceCode = "personList",

            serviceVersion = "v1",

            objectType = XRoadObjectType.SERVICE

        };

        var client = new XRoadClientIdentifierType {

            xRoadInstance = "ee-dev",

            memberClass = "COM",

            memberCode = "11333578",

            subsystemCode = "misp2-01",

            objectType = XRoadObjectType.SUBSYSTEM

        };

 

        var request = new personList {

            request = new personListRequest {

 

                givenName = "",

                surname = "Tamm"

            }

        };

        //Create client object

        var serviceClient = new pplService.aktorstestPortTypeClient();

 

        //Make service call

        var response = serviceClient.personList(

            client: ref client,

            service: ref service,

            protocolVersion: ref protocolVersion,

            id: ref id,

            userId: ref userId,

            personList1: request);

 

         

    }

 

}





Last modified: Wednesday, 1 March 2017, 4:51 PM