TechRefGuide

Epicor ERPEpicor WCF Services Developer Guide 10.0.700 Disclaimer This document is for informational purposes only and is subject to change without notice. This document and its contents, including the viewpoints, dates and functional content expressed herein are believed to be accurate as of its date of publication. However, Epicor Software Corporation makes no guarantee, representations or warranties with regard to the enclosed information and specifically disclaims any applicable implied warranties, such as fitness for a particular purpose, merchantability, satisfactory quality or reasonable skill and care. As each user of Epicor software is likely to be unique in their requirements in the use of such software and their business processes, users of this document are always advised to discuss the content of this document with their Epicor account manager. All information contained herein is subject to change without notice and changes to this document since printing and other important information about the software product are made or published in release notes, and you are urged to obtain the current release notes for the software product. We welcome user comments and reserve the right to revise this publication and/or make improvements or changes to the products or programs described in this publication at any time, without notice. The usage of any Epicor software shall be pursuant to an Epicor end user license agreement and the performance of any consulting services by Epicor personnel shall be pursuant to Epicor's standard services terms and conditions. Usage of the solution(s) described in this document with other Epicor software or third party products may require the purchase of licenses for such other products. Where any software is expressed to be compliant with local laws or requirements in this document, such compliance is not a warranty and is based solely on Epicor's current understanding of such laws and requirements. All laws and requirements are subject to varying interpretations as well as to change and accordingly Epicor cannot guarantee that the software will be compliant and up to date with such changes. All statements of platform and product compatibility in this document shall be considered individually in relation to the products referred to in the relevant statement, i.e., where any Epicor software is stated to be compatible with one product and also stated to be compatible with another product, it should not be interpreted that such Epicor software is compatible with both of the products running at the same time on the same platform or environment. Additionally platform or product compatibility may require the application of Epicor or third-party updates, patches and/or service packs and Epicor has no responsibility for compatibility issues which may be caused by updates, patches and/or service packs released by third parties after the date of publication of this document. Epicor® is a registered trademark and/or trademark of Epicor Software Corporation in the United States, certain other countries and/or the EU. All other trademarks mentioned are the property of their respective owners. Copyright © Epicor Software Corporation 2014. All rights reserved. No part of this publication may be reproduced in any form without the prior written consent of Epicor Software Corporation. 10.0.700 Revision: July 03, 2014 12:16 p.m. Total pages: 28 sys.ditaval .............................................................25 WSHTTPBinding Explanation...............................................................................5 When to Use the TCP Transport...............................................5 When to Use HTTP Transport.............................................................................................................................................................................................................................................................................................Config File....................................................................................................................................................................................14 Setting Up SSL..............................................................................................................................................................................Epicor WCF Services Developer Guide Contents Contents Introduction................................................25 BasicHTTPBinding Explanation...........0...................................6 Add the Web Service References......26 Epicor ERP | 10............25 Update the Web..........................................................................................................................................................................................20 Create Site Binding......................................................................................................................................................24 Enable HTTP Endpoints...............................................................................................................................4 Conventions.................................................8 Add Functionality to the Program Class...................................................................................................4 Overview...........................20 Connect the Application Server................................................................................................................................................................................................................................................................................7 Add Helper Classes........700 3 ...............................................................................................6 WCF Services Example.......................................................................................................................................................................................................................5 HTTP Transport.............................................4 Audience...............................................................11 Code the Main Method..................................................................................................................................................................................4 Prerequisites...............6 Create the Visual Studio Project..................................................................................................................................................... custom storefront applications.NET 4 platform. how to configure the web services for different scenarios. developers can make Epicor data available for use in third party applications. This guide assumes you have already installed your Epicor application server. This document describes how to consume the Epicor WCF-Services. This guide is written for the . This document also assumes you have a configured Epicor client application on your local development machine. By leveraging web services. Audience This guide is intended for developers responsible for integrating with Epicor ERP using web services.700 . Visual Studio 2012. . and Internet Information Services (IIS). You should also understand the basic concepts behind web services and WCF. and other purposes. • When this document refers to Internet Information Services (IIS).0. so application server installation instructions are not included in this document.0. it refers to the server where you installed the Epicor application server. and other information developers may find useful when working with Epicor Web Services. Conventions This guide uses the following conventions.Introduction Epicor WCF Services Developer Guide Introduction Welcome to the Epicor WCF-Services Developer Guide. • Code samples appear in the follow font style: static void Main(string[] args) { string myString = "Test". These web services also can move Epicor data into Java or other programming environments. You will need access to the client assemblies to complete some coding projects.NET 4. 4 Epicor ERP | 10. Prerequisites This document assumes you have a working knowledge of C#. Epicor WCF Services Developer Guide Overview Overview The Epicor WCF services support two transport mechanisms: net. The most common application consists of Web-browser clients that communicate with a Web server. Note that this reliable delivery applies between two TCP/IP nodes. optional data. Connection-based means that a communication session between hosts is established before exchanging data. which contains the status of the request. A host is any device on a TCP/IP network identified by a logical IP address. In WCF. When to Use HTTP Transport Microsoft states the following about when you should use HTTP Transport: HTTP is a request/response protocol between clients and servers. TCP notifies the sender of packet delivery. When to Use the TCP Transport Microsoft states the following about when you should use TCP Transport: TCP is a connection-based.Config file. no matter how many intermediate nodes they may include.0. This binding is the fastest WCF binding for scenarios that involve communicating between different machines. the HTTP transport binding is optimized for interoperability with legacy non-WCF systems. which applies between endpoints. and is not the same thing as WS-ReliableMessaging. The client sends a request to a server. the TCP-based binding is faster. You also need to properly configure the application server’s Web. such as a Web page. The WCF TCP transport is optimized for the scenario where both ends of the communication are using WCF. When the server receives a request.700 5 . Specifically. or other information is returned. guarantees that packets are delivered in the same order in which they are sent. and ensures that data packets are not duplicated. retransmits lost packets. stream-oriented delivery service with end-to-end error detection and correction. TCP provides reliable data delivery and ease of use. If all communicating parties are using WCF. Epicor ERP | 10. an error message. Each of these mechanism requires you follow a different approach when you use them. If successful. which listens for client request messages.tcp and http/ https. it returns a response. 2004). set up the following items: • IIS needs to be configured for SSL. 6. • Your application server must also be configured to enable the BasicHttpBinding and WSHttpBinding endpoints. Click OK. For information on setting up your application server to use these two forms of HTTP transport. you specify how to transfer data across a network between endpoints through a binding.Supports the SOAP 1. You will create a sample C# project that consumes the ABCCode service using either BasicHttpBinding or WSHttpBinding. For HTTP Transport. 7. while WSHttpBinding sends it in an encrypted and secured manner. • BasicHttpBinding . 4. Select the location where you will save the project. verify Visual C# is selected in the tree view. and other services that conform to the WS-I Basic Profile 1. the Epicor application server is located on a machine named ‘localhost’ and the application name is ‘ERP100500’. enter AbcCodeServiceClient. select Console Application. By default BasicHttpBinding sends data in plain text. 3. If you have not done this. WCF Services Example This section describes the process through which Epicor web services are consumed. 2. this document explores BasicHttpBinding and WSHttpBinding.2 and WS-Addressing specifications. Launch Microsoft Visual Studio .HTTP Transport Epicor WCF Services Developer Guide HTTP Transport In WCF. Requirements To complete this example. For the project Name. To illustrate this example. Next in the Detail panel. review the Enable HTTP Endpoints section later in this guide. Select the File > New > Project menu item. When you see these values in the code samples. • WSHttpBinding . Create the Visual Studio Project ® ® 1.Used when you communicate with ASMX-based web services. and each binding is made up of a sequence of binding elements. replace them with values that match your environment. 5.0. In the New Project dialog box.700 . web clients. review the Setting Up SSL section later in this guide. This process is illustrated through an ABCCode service example. 6 Epicor ERP | 10.1 (Web Services Interoperability Organization. 4. The address for this service is like http://localhost/ERP100500/Erp/BO/AbcCode. enter Epicor.svc. 6.0. Click OK. Click Go. In the Address field. The AbcCode service maintains ABC codes. the URL is the http://localhost/ERP100500/ICE/Lib/SessionMod. enter the URL to your SessionMod service. For this example. 3. 2. 1. Epicor ERP | 10.svc value. In the Solution Explorer. Repeat steps 1-5 again. such as the company or site you are working against. right-click the AbcCodeServiceClient project item and select the Add> Service Reference… menu item. The reference is added to your project. The details for the service display. For the Namespace field.700 7 .AbcCodeSvc. This service also changes certain session properties. 5. This time add a reference to the AbcCode service.SessionModSvc.Epicor WCF Services Developer Guide HTTP Transport Add the Web Service References You need to reference the SessionMod and AbcCode services. and you use a namespace value of Epicor. The Add Service Reference dialog box displays. The SessionMod service creates a session on the server that persists between method calls. so next indicate this class inherits from MessageHeader: class SessionInfoHeader: MessageHeader b. Next in the Name field. You have already added a using statement for the System. Your SessionInfoHeader must inherit from the System. 5. To do this. You override these properties to implement them. On the List view.Description. a. right-click the AbcCodeServiceClient project item. using System.MessageHeader class. class CustomMessageInspector { } Directly beneath the closing curly brace for the CustomMessageInspector class. These steps note where you could use the Epicor provided classes in place of the classes you enter through code. 7. 3. You next work on the SessionInfoHeader. enter CustomMessageInspector. The Add New Item dialog box displays. You can provide this header through multiple methods.ServiceModel.ServiceModel. MessageHeader is an abstract class. At the top of the file you see the standard using statements.Dispatcher. This class represents the session information SOAP header item. Click Add. Any session level properties the user may set persist between each server call as long as each call uses the same session ID. 1. so it contains two properties (Name and Namespace) and a method (OnWriteHeaderContents).Channels namespace. using System. 4.Channels. However before you do any work on it.700 .HTTP Transport Epicor WCF Services Developer Guide Add Helper Classes One feature of the Epicor application server is the client can institute a session on the server. You need to add the following custom using statements to this list: using System.0. The process described below does not require you take a dependency on any Epicor assemblies. This opens the file in the Editor window. 6. The 8 Epicor ERP | 10. Select the Add > Class… menu item.ServiceModel. you provide a SessionInfo SOAP header. add two other classes to this file.ServiceModel. add these classes: class SessionInfoHeader { } class HookServiceBehavior { } 8.cs file. 2. Return to the Solution Explorer and click on the CustomMessageInspector. In the Solution Explorer. the Class item should be selected by default. Visual Studio creates an empty class for you named CustomMessageInspector.ServiceModel.Channels. Hosting". public HookServiceBehavior(Guid SessionId. } 9. class HookServiceBehavior : IEndpointBehavior b.Description. Use this method to ensure an endpoint has a certain configuration setting enabled.WriteElementString("SessionID". • ApplyDispatchBehavior -. This class implements the System.IEndpointBehavior interface. set. Do the following: a. To complete this class. } public override string Name { get { return "SessionInfo". add two properties that store the user’s Epicor session Id and Epicor user Id: public Guid SessionId { get. You write the contents of the header through this code block: protected override void OnWriteHeaderContents(System. MessageVersion messageVersion) { writer.or g/2004/07/Epicor. set.WriteElementString("UserID". examines. You can then implement methods to extend run-time behavior for an endpoint in the client application. Next update the HookServiceBehavior class. and uses other requirements. You must implement all four methods.datacontract. • Validate -.XmlDictionaryWri ter writer. SessionId. class HookServiceBehavior : IEndpointBehavior { private Guid _sessionId. add two private variables that hold the user’s Session ID and Epicor User ID. Specify that the HookServiceBehavior implements the IEndpointBehavior interface.Epicor WCF Services Developer Guide HTTP Transport OnWriteHeaderContents method is called when the header contents are serialized.ServiceModel. c.ToString()). EpicorUserId).Modifies.Modifies. } public string EpicorUserId { get. or inserts extensions to an endpoint in a client application.Hosting". • ApplyClientBehavior -. } } c. writer. Now create a constructor method for the class that takes for parameters a Guid and a string. examines. @"http://schemas. @"http://schemas.datacontract . private string _epicorUserId. string EpicorUserId) { Epicor ERP | 10. This constructor then uses those values to set the class level variables you created. The interface exposes four methods: • AddBindingParameters -.Confirms a ServiceEndpoint meets specific requirements.Xml. After the opening curly brace. or inserts extensions to endpoint-wide execution in a service application.org/2004/07/Epicor.Passes custom data at runtime to enable bindings to support custom behavior. supports a particular feature. but you only add code to the ApplyClientBehavior method.0.700 9 . } } public override string Namespace { get { return "urn:epic:headers:SessionInfo". string EpicorUserId) { _sessionID = SessionId.ServiceModel. _epicorUserId = EpicorUserId. as this method is where you place the SessionInfo header information. ClientRuntime c lientRuntime) { clientRuntime. Endpoi ntDispatcher endpointDispatcher) { } public void Validate(ServiceEndpoint endpoint) { } 10.HTTP Transport Epicor WCF Services Developer Guide _sessionId = SessionId.Add(new CustomMessageInspector (_sessionId. } Tip You may notice that Visual Studio displays errors that refer to code in the ApplyClientBehavior method. Add a constructor method for the class that uses for parameters a Guid and a string. This class adds the SessionInfo header to the outgoing request headers. } public void ApplyDispatchBehavior(ServiceEndpoint endpoint. object correlationState) { } public object BeforeSendRequest(ref Message request. Specify the CustomMessageInspector class implements the IClientMessageInspector interface. class CustomMessageInspector : IClientMessageInspector { private Guid _sessionID.0. Assign their values to the two class level variables you added. as they will stop once you implement the CustomMessageInspector class. You can ignore these messages. } d. private string _epicorUserId.700 . Add two private class level variables that hold the Epicor session Id and user Id. only add code to the BeforeSendRequest method. _epicorUserId = EpicorUserId. In this example. _epicorUserId)). Now implement the CustomMessageInspector class.ClientMessageInspectors. public void AfterReceiveReply(ref Message reply. class CustomMessageInspector : IClientMessageInspector b. IClientChannel channel) { 10 Epicor ERP | 10. public CustomMessageInspector(Guid SessionId. Provide implementations for the four methods defined by the interface. c. d. public void AddBindingParameters(ServiceEndpoint endpoint. BindingParamet erCollection bindingParameters){ } public void ApplyClientBehavior(ServiceEndpoint endpoint. System. Enter the two methods required for the IClientMessageInspector interface. This interface defines a message inspector object that can be added to the MessageInspectors collection to view or modify messages. a. } return request. binding. review these steps again to correct these errors. you configure these endpoint bindings in code. System. but the project does not actually function.SessionModSvc.AbcCodeSvc.MaxValue. For this example.ServiceModel.Epicor.MaxDepth = maxBindingSize. AbcCodeServiceClient. request. binding.MaxArrayLength = maxBindingSize. Tip You can also configure the endpoint bindings through the application configuration file (app. } At this point your helper classes are complete.MaxReceivedMessageSize = maxBindingSize. class Program { private enum EndpointBindingType { SOAPHttp. const int maxBindingSize = Int32. you start by defining an enumeration that specifies which binding to use.Add(sessionHeader). private static WSHttpBinding GetWsHttpBinding() { var binding = new WSHttpBinding().config). so you add the following using statements to this list: using using using using using using System. Add Functionality to the Program Class You next add code to the Program class provided in the Program. These methods programmatically create the endpoint bindings.ReaderQuotas.Epicor. You next code the first two helper methods. System. If you do.0. Visual Studio has already added the standard using statements. BasicHttp } 2.ReaderQuotas. AbcCodeServiceClient. System.Reflection.ServiceModel.ReaderQuotas.Empty) { var sessionHeader = new SessionInfoHeader() { SessionId = _sess ionID.ReaderQuotas.Net.Headers. binding. binding.ReaderQuotas. First add the using statements. 1. Now enter the GetWsHttpBinding method.MaxNameTableCharCount = maxBindingSize. b.MaxBytesPerRead = maxBindingSize.Channels. binding.cs code file. However you can run a test build of the project to make sure you don’t have build errors. This method can be added immediately after the Main method. Epicor ERP | 10. a. binding.Epicor WCF Services Developer Guide HTTP Transport if (_sessionID != null && _sessionID != Guid. These methods do the work of creating an instance of the service client classes you defined when you added the service references. EpicorUserId = _epicorUserId }. Since this project demonstrates the ability to call into the Epicor services using either BasicHttpBinding or WSHttpBinding. You add three helper methods to this class that are called from the Main method.700 11 .MaxStringContentLength = maxBindingSize. MaxStringContentLength = maxBindingSize. 3.0. TInterface>( string url.MaxDepth = maxBindingSize.Security.MaxValue. public static BasicHttpBinding GetBasicHttpBinding() { var binding = new BasicHttpBinding(). string password.ReaderQuotas. binding. } Notice this code first creates a new instance of the binding. return binding. you can retrieve large record sets. binding.ClientCredentialType = BasicHttpMessageCred entialType.Message. set it to TransportwithMessageCredential. The reader quotas element defines the constraints on the complexity of the SOAP messages processed by endpoints configured through this binding. • For the WSHttpBinding. binding.Message. EndpointBindingType bindingType) where TClient : ClientBase<TInterface> where TInterface : class { 12 Epicor ERP | 10. Add the following method directly below the GetWsHttpBinding method. It then sets the maximum values for the message size and reader quotas. string username.MaxReceivedMessageSize = maxBindingSize. Now add the last helper method – GetClient. The code next specifies the security mode the binding will use: • For the BasicHttpBinding. Unfortunately these two bindings inherit from different classes and the ReaderQuotas property is defined on each base class instead of common base class from which they both inherit. set the security mode to Message as the WSHttpBinding encrypts its messages by default. return binding.ReaderQuotas. binding. This mode indicates you use https and that the service is configured with a certificate. With the Epicor application. For both bindings. set the client credential type to UserName to indicate you want to include a UserName token in the header. Name the second method GetBasicHttpBinding. binding. SOAP message security provides the client authentication. binding.Security.MaxArrayLength = maxBindingSize.ReaderQuotas.UserName. this method creates a new.Security.MaxBytesPerRead = maxBindingSize. binding.ReaderQuotas.MaxNameTableCharCount = maxBindingSize.Mode = BasicHttpSecurityMode.HTTP Transport Epicor WCF Services Developer Guide binding. private static TClient GetClient<TClient. This method creates an instance of the client classes.700 .UserName.Message.TransportWithMessageCr edential. properly configured instance of the BasicHttpBinding class. Notice this method is similar to the first method.Security. const int maxBindingSize = Int32.ClientCredentialType = MessageCredentialTyp e.Mode = SecurityMode.ReaderQuotas. binding. } c. binding. Add the following method directly after the GetBasicHttpBinding method. SOAPHttp: binding = GetWsHttpBinding(). Lastly this code assigns the user name and password to the ClientCredentials instance on the client class.SendTimeout = operationTimeout. each has a value of one minute.americas. Place this code immediately after the ‘switch(bindingType)’ block: TimeSpan operationTimeout = new TimeSpan(0.700 13 . If this is a legitimate remote endpoint.net'.ReceiveTimeout = operationTimeout. Once the code has the EndpointAddress and binding. e ndpointAddress).UserName. 12.CloseTimeout = operationTimeout. The expected DNS identity of the remote endpoint was 'l303415' but the remote endpoint provided DNS claim 'L303415.ClientCredentials. binding. if (!string.” Epicor ERP | 10. TClient client. If you receive operation timeout errors when calling a service. binding. switch (bindingType) { case EndpointBindingType. case EndpointBindingType. adjust the timeout values on the binding. binding.ClientCredentials.OpenTimeout = operationTimeout. the service is hitting one of these timeouts. binding.Password = password. In the above example.0. } client = (TClient)Activator. If you receive errors like “The open operation did not complete within the allotted timeout…”. } This code first creates an EndpointAddress instance that represents the URL of the service you are calling. binding.epicor.UserName = username.Epicor WCF Services Developer Guide HTTP Transport Binding binding = null.BasicHttp: binding = GetBasicHttpBinding().IsNullOrEmpty(username) && (client. To correct this error. it creates an instance of the client class. You can also add a couple items to this code that help correct errors. you can fix the problem by explicitly specifying DNS identity 'L303415. var endpointAddress = new EndpointAddress(url). 0). break. } return client. This code handles error messages similar to the following: “Identity check failed for outgoing message.UserName. A binding has four timeout values: • OpenTimeout • CloseTimeout • ReceiveTimeout • SendTimeout By default.epicor. break. notice you set the timeout values to twelve minutes. You may need to make another code change to take into account the DNS identity difference between the service URL and the identity specified in the certificate used by the web server.net' as the Identity property of EndpointAddress when creating channel proxy. The code then creates a binding based upon the EndpointBindingType passed in (you defined the EndpointBindingType enumeration in step 1).CreateInstance(typeof(TClient).ClientCredentials != nu ll)) { client.americas. adjust the timeout values. client. modify. You also enter an UriBuilder code line that creates the URL for the services. You can toggle the value assigned to this variable to test the two bindings: EndpointBindingType bindingType = EndpointBindingType. Code the Main Method Now code the Main method and call the Epicor services. This prevents the method from trying to validate the certificate with the known authorities.0. 3. 14 Epicor ERP | 10. string epicorUserID = "manager". This instance determines which endpoint binding to use at runtime. } UriBuilder builder = new UriBuilder(scheme. ServicePointManager. var endpointAddress = new EndpointAddress(new Uri(url).net"). errors) => { return true. save . certifi cate. Now create two variables that hold the Epicor User ID and Password. 1. This code speeds up calls to the services. This example demonstrates how to initiate a server session and associate that session with your server calls. It also demonstrates how to create. replace the line: var endpointAddress = new EndpointAddress(url). }. endpointIdentity).BasicHttp) { scheme = "https". 4.america s. You will also need to add a reference to the System. To do this.SOAPHttp. You can also specify a DnsEndpointIdenity object to the EndpointAddress you created. string scheme = "http". This code tells the ServicePointManager (a class that provides connection management for HTTP connections) to validate the server certificate. Next use code to determine what scheme will connect (HTTP vs. be sure to enter the name of the machine that hosts your services instead of “localhost”. One way is to change the service URL so it uses the fully qualified machine name. if (bindingType == EndpointBindingType. HTTPS).ServerCertificateValidationCallback += (sender. be sure to include the following code. chain. and delete a record.700 . Set the value of these variables to match a valid User ID in your Epicor application. 2. In the constructor for the UriBuilder.epicor. With this line: DnsEndpointIdentity endpointIdentity = new DnsEndpointIdentity("L303415. "localhost"). string epiorUserPassword = "manager". In production code. Tip This example uses a plain string to hold the password. you store the password though a SecureString instance. If you use a self-signed certificate in IIS.HTTP Transport Epicor WCF Services Developer Guide You can resolve this error in two ways.IdentityModel assembly. Next create a variable that is an instance of the EndpointBindingType you created earlier. However for your code.Add(new HookServiceBehavior(ses sionId. set the Path property of the UriBuilder to the path of the service. var ts = new ABCCodeTableset().ToString().svc". ABCCodeSvcContract>( builder. abcCodeClient.0. passing it to the Guid you receive. This adds the SessionInfo header to each subsequent call. SessionModSvcContractClient sessionModClient = GetClient<SessionModSvcContr actClient. You can now set the required fields and call the Update method on the service to save the record. epiorUserPassword. SessionModSvcContract>( builder. 7. the code sets the ABCCode field for the new row to a “G” value. the Epicor 10 appserver name is “ERP100500”. This call returns a new row in the tableset with default values.StockValPcnt = 100.Equals("A". builder.ABCCode. newRow. First call the SessionModSvc Login method to establish a session in the appserver. Then call the GetNewABCCode method to create a new ABCCode record. Epicor ERP | 10. but it does not save the row to the database.Where(n => n.700 15 .Add(new HookServiceBehavior(sessio nId. epicorUserID. epicorUserID)).Endpoint.Path = "ERP100500/Ice/Lib/SessionMod. This code goes between the curly braces after the if (newRow != null) statement you added in the previous step. sessionModClient.Uri.svc". var newRow = ts. Then create an instance of the HookServiceBehavior class for each client instance. replace this value with your appserver name.Endpoint. abcCodeClient. builder. Make calls to the AbcCodeSvc service. newRow. Now use the services.Uri.GetNewABCCode(ref ts). bindingType).CountFreq = 30.In variantCultureIgnoreCase)).FirstOrDefault().Path = "ERP100500/Erp/BO/AbcCode. the row should return with the RowMod field set to “A”.Epicor WCF Services Developer Guide HTTP Transport 5. In this example code. When you call a “GetNew” methods on the Epicor services.Empty. if (newRow != null) { } 8. First create an instance of an empty ABCCodeTableset to pass into the service.EndpointBehaviors.ABCCode = "G". epicorUserID)).Login().ToString(). ABCCodeSvcContractClient abcCodeClient = GetClient<ABCCodeSvcContractClient . Before creating each instance. these classes were created when you added the service references in Step 2. Now add instances of the two service client classes created by Visual Studio. bindingType). epiorUserPassword. 6. This returns a Guid that identifies the session. StringComparison.RowMod. sessionId = sessionModClient. use a value that does not exist. The code uses this to select a new row from the ABCCode table in the tableset. epicorUserID. Guid sessionId = Guid. newRow.EndpointBehaviors. In this example. You should always code defensively and have code that can handle exceptions that may occur when calling the application server. 9.GetValue(ts.Any()) { } 10. • Second.700 . var fields = backupRow. foreach(var field in fields) { if (field. ts. 16 Epicor ERP | 10.Runtime.Instance | Bind ingFlags. set the RowMod field in the row to a “U” value.GetByID("G"). To finish the AbcCodeSvc service. ts = abcCodeClient. you null out the tableset and call GetByID again to demonstrate the record was updated.GetType().PropertyType == typeof(System. delete the record. if (ts != null && ts. } var fieldValue = field. ts. Again you try to call the GetByID method to retrieve the record.HTTP Transport Epicor WCF Services Developer Guide abcCodeClient.Update(ref ts). Since you saved the record.ABCCode.ABCCode[0]). ts = null.Public). If you do not do this. ABCCodeRow backupRow = new ABCCodeRow().Extensio nDataObject)) { continue. set the RowMod field to a “D” value and call the Update method.Any()) code added in the previous step. ts = abcCodeClient. Other possible values for the ExceptionKindValue are “ServerException”. } 11.ABCCode. Place the following code immediately after the call to Console.CountFreq). field. server business logic often requires both the ‘before’ and ‘updated’ versions of the row be sent. abcCodeClient. After saving the change. This code goes inside the curly braces that appear after the if(ts != null && ts. ts.ABCCode[0].0. Next update some values on the record and save it back to the server again. ts = null.Update(ref ts). you next fetch it from the server. This code example demonstrates two important concepts: • First. when you update an existing record.Serialization. your changes are not saved. The following code demonstrates wrapping the service call in a try/catch block.ABCCode[0].RowMod = "U". if (ts != null && ts.ABCCode[0]. fieldValue). This time no record should exist.Any()) { Console.CountFreq = 45. To delete a record. Replace the “G” in the call to GetByID with the code you entered in the previous step.SetValue(backupRow. } ts.Add(backupRow).WriteLine and inside the curly braces that surround it.ABCCode. This example demonstrates your record was saved by the previous code. This requires you make a copy of the row and then add it to the table before making changes. “BLException”. so a “record not found” error should get thrown by the application server.WriteLine("CountFreq = {0}".GetProperties(BindingFlags.ABCCode.GetByID("G"). } Console.Detail.Equals("RecordNotFound".SOAPHttp.WriteLine("Record deleted. certif icate. This releases the server session and makes sure you are not needlessly consuming license seats. “DuplicateRecord”. builder. This code goes after the closing curly brace that is tied to the “if(newRow != null)” block you added in step 7: if (sessionId != Guid. abcCodeClient. } else { Console. try { ts = abcCodeClient. chain. if (bindingType == EndpointBindingType.svc".AbcCodeSvc.WriteLine(ex.InvariantCultureIgnoreCase)) { Console. EndpointBindingType bindingType = EndpointBindingType. string epiorUserPassword = "Epicor123". Remember you can change the value of the bindingType variable to test the BasicHttpBinding and WSHttpBinding endpoint bindings. Lastly. } catch (FaultException<Epicor.Path = "ERP100500/Ice/Lib/SessionMod.BasicHttp) { scheme = "https". } UriBuilder builder = new UriBuilder(scheme."). StringCompar ison.ServerCertificateValidationCallback += (sender. SessionModSvcContractClient sessionModClient = GetClient<SessionModSvcCont ractClient. “ConversionPending”.Logout().Update(ref ts).Message). You can now compile it in Visual Studio by selecting the Build > Build Solution option.Epicor WCF Services Developer Guide HTTP Transport “SqlException”. Correct compilation errors. ts.EpicorFaultDetail> ex) { if (ex. } } 12. “VersionMismatch” and “UnknownException”. "localhost"). The full code for the Main method displays below for your reference: static void Main(string[] args) { ServicePointManager.ExceptionKindValue. call the LogOut method on the SessionModSvc.700 17 . }. This completes the code for the Main method. string epicorUserID = "manager".ReadLine(). Run the code by selecting the Debug > Start Debugging menu option. SessionModSvcContract>( Epicor ERP | 10.ABCCode[0]. errors) => { return true.Empty) { sessionModClient.RowMod = "D". string scheme = "http".0.GetByID("G"). newRow.StockValPcnt = 100.svc".CountFreq).RowMod = "U".Inst ance | BindingFlags.GetByID("G").Endpoint. epicorUserID.ABCCode. sessionModClient.Equals("A".ABCCode[0]. StringComparison.700 .RowMod.FirstOrDefault().Path = "ERP100500/Erp/BO/AbcCode.Add(new HookServiceBehavior(se ssionId.ABCCode[0].GetByID("G"). ts.PropertyType == typeof(System.ABCCode[0]).Public). epicorUserID)). newRow. var ts = new ABCCodeTableset().ABCCode.Endpoint. var fields = backupRow.Where(n => n.Update(ref ts).EndpointBehaviors. ts. epicorUserID.ToString(). ts = null.CountFreq = 45. ts = abcCodeClient. 18 Epicor ERP | 10.SetValue(backupRow.ABCCode[0]. var newRow = ts.GetType().Serializati on.HTTP Transport Epicor WCF Services Developer Guide builder.GetProperties(BindingFlags. foreach(var field in fields) { if (field.Any()) { ABCCodeRow backupRow = new ABCCodeRow().GetNewABCCode(ref ts). field.Runtime. builder. abcCodeClient. epiorUserPassword. bindingType). epiorUserPassword. abcCodeClient. } var fieldValue = field. if (ts != null && ts. } ts.Uri. ABCCodeSvcContract>( builder.Login().Uri.WriteLine("CountFreq = {0}". epicorUserID)).I nvariantCultureIgnoreCase)). ts = abcCodeClient. if (ts != null && ts.CountFreq = 30. ts.0.ExtensionDataObject)) { continue. if (newRow != null) { newRow.ABCCode. sessionId = sessionModClient. Guid sessionId = Guid. ts = null.ABCCode.Add(backupRow). abcCodeClient.EndpointBehaviors. abcCodeClient. bindingType).Any()) { Console. ABCCodeSvcContractClient abcCodeClient = GetClient<ABCCodeSvcContractClien t.GetValue(ts.ToString().ABCCode = "G".Empty.Add(new HookServiceBehavior(sessi onId. fieldValue).Update(ref ts). ReadLine().Message).Empty) { sessionModClient.ExceptionKindValue.Detail.700 19 .0.WriteLine("Record deleted.Update(ref ts).Logout()."). } Console. S tringComparison.WriteLine(ex.Equals("RecordNotFound".GetByID("G").RowMod = "D".EpicorFaultDetail> ex) { if (ex.InvariantCultureIgnoreCase)) { Console. } } } } } if (sessionId != Guid. } else { Console. abcCodeClient.AbcCodeSvc.Epicor WCF Services Developer Guide HTTP Transport ts. } catch (FaultException<Epicor. try { ts = abcCodeClient. } Epicor ERP | 10.ABCCode[0]. 0. click the "Create Self-Signed Certificate" option: 20 Epicor ERP | 10. The following steps outline how to configure IIS to use a self-signed certificate. Click Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager. 2. Create Site Binding 1. Open the Internet Information Services (IIS) Manager console.Setting Up SSL Epicor WCF Services Developer Guide Setting Up SSL You have two options for setting up SSL in Internet Information Services (IIS): • Obtain an SSL certificate from a known certificate authority (CA) such as VeriSign or GeoTrust. select the server node and then double-click the Server Certificates icon in the list view: 3. Navigate to the tree view.700 . • Create a self-signed certificate through the IIS Management console. Now from the Actions panel. Epicor WCF Services Developer Guide Setting Up SSL 4. Highlight the Subject property. Click OK. In the Create Self-Signed Certificate dialog box. This launches the Site Bindings editor. Write down this value. 7. Select a site in the tree view (for example. 9. a. Now in the certificate dialog. and delete bindings for your Web site. select the View option. Now in the Actions pane. You next create an SSL Binding. select the Bindings option. b.0. Epicor ERP | 10. The certificate is created. select the Details tab. as you will need it later. from the context menu. enter a name for the certificate such as Epicor-Dev. ‘Default Web Site’). 6. edit. Use this window to create. right-click your new certificate.700 21 . In the Server Certificates panel. 8. 5. 10. To save your new binding. d. 22 Epicor ERP | 10. a. click the Add… button.700 .Setting Up SSL Epicor WCF Services Developer Guide c. From the Type drop-down list. e. click OK. To add your new SSL binding. select the certificate you created in the previous steps. The default settings for a new binding are set to HTTP on port 80. In the Actions pane.0. click the link associated with the https binding. select the https option. f. Now verify the SSL binding works. From the SSL Certificate drop-down list. under the Browse Web Site section. not by a trusted Certificate Authority (CA).Epicor WCF Services Developer Guide Setting Up SSL b. Internet Explorer (IE) 7 and above will display an error page. Click the Continue to this website (not recommended) link. You should see a page similar to this example: Epicor ERP | 10. Internet Explorer 7 and above will trust the certificate if you add it to the list of Trusted Root Certification Authorities in the certificates store on the local computer or in Group Policy for the domain.700 23 . Tip This error occurs because the self-signed certificate was issued by your computer. c.0. 24 Epicor ERP | 10. In Notepad open the Web.americas.epicor. 3. you make your appserver aware of this certificate.700 . Add a serviceCertificate element to the serviceCredentials element.0.net" storeLocation=" LocalMachine" storeName="My" x509FindType="FindBySubjectName" /> 4. Locate the system. 2. Save the Web.serviceModel/behaviors/serviceBehaviors/behavior/serviceCredentials element. Change the findValue attribute to be the subject value you noted in the previous section. 1.Setting Up SSL Epicor WCF Services Developer Guide Connect the Application Server Now that you have IIS configured to use SSL.config file. 5.config file associated with you application server. The serviceCertificate element looks like the following: <serviceCertificate findValue="L303415. serviceModel/bindings section.config file so they use this method of transport. make sure it uses the SSL protocol. configure endpoint bindings in your web.700 25 . 2. You also need to provide a username/password token to specify a security mode of “TransportWithMessageCredential”. Locate the system.config file.0.serviceModel/protocolMapping section and add your two endpoints: <remove scheme="https" /> <add scheme="https" binding="basicHttpBinding" bindingConfiguration="B asicHttp" /> <remove scheme="http" /> <add scheme="http" binding="wsHttpBinding" bindingConfiguration="SOAPH ttp" /> 4. this ensures the communication is encrypted. Open the web.Epicor WCF Services Developer Guide Enable HTTP Endpoints Enable HTTP Endpoints If you need clients to connect to your Epicor application server using HTTP. 1. The following topics describe how you enable HTTP endpoints. You do this by specifying transport security. By Epicor ERP | 10. Locate the system.config for your application server in Notepad or a similar text editor. <basicHttpBinding> <binding name="BasicHttp" maxReceivedMessageSize="2147483647"> <security mode="TransportWithMessageCredential"> <message clientCredentialType="UserName" /> </security> <readerQuotas maxArrayLength="2147483647" maxBytesPerRead="214748364 7" maxDepth="2147483647" maxStringContentLength="2147483647" /> </binding> </basicHttpBinding> <wsHttpBinding> <binding name="SOAPHttp" maxReceivedMessageSize="2147483647"> <security mode="Message"> <message clientCredentialType="UserName" /> </security> <readerQuotas maxArrayLength="2147483647" maxBytesPerRead="2147483 647" maxDepth="2147483647" maxStringContentLength="2147483647" /> </binding> </wsHttpBinding> 3. Save the web.Config File This section describes how to configure the BasicHttpBinding to use the https and the WSHttpBinding to use plain http secured through X509 certificates. add two bindings to this section. If they do not exist. BasicHTTPBinding Explanation Since BasicHttpBinding communicates in plain text. Update the Web. config file (review the Setting Up SSL section for more information). You can then use http to communicate with the server. By default. 26 Epicor ERP | 10. the SOAP body is Encrypted and Signed.700 .Enable HTTP Endpoints Epicor WCF Services Developer Guide setting the message client credential type to “UserName”. specify the message is encrypted by default. as security is provided using SOAP message security.serviceModel/behaviors/serviceBehaviors/behavior/serviceCredentials element in your web. the client must authenticate the server using a UserName credential. WSHTTPBinding Explanation If you use WSHttpBinding. This requires that an SSL certification is specified in the system. You specify the client credential type is a username and you also specify the same reader quotas as in the BasicHttpBinding. it is recommended you set these values to their maximum.0. Do this by indicating the security mode is "message". The reader quotas element of the binding defines the constraints on the complexity of the SOAP messages processed by the configured binding endpoints. Because you can retrieve large records through the Epicor application. create 6 P prerequisites 4 Epicor ERP | 10.config 25 http transport 6 http transport. add 7 wshttpbinding 26 V visual studio project. site binding 20 H T helper classes. full code example 17 wcf services example 6 web services references. enable 25 http endpoints.Epicor WCF Services Developer Guide Index Index B program class. when to use 5 M W main method 14 main method.0. add functionality 11 basichttpbinding 25 S C conventions 4 ssl set up 20 ssl set up. when to use 5 tcp transport. web.700 27 . add 8 http endpoints. connect application server 24 ssl set up. com. you need a Site ID and an EPICweb account. To create an account. .Additional information is available at the Education and Documentation areas of the EPICweb Customer Portal.epicor. go to http://support. To access this site.