Overview of Endpoints on Applications 

  • Article

In Application Designer, endpoints on applications define services that they provide or specify the requirement to use services. Endpoints also provide connection points so that you can configure communication pathways between applications by connecting their endpoints. You can also constrain an application endpoint by limiting the types of logical server endpoints to which it can bind when defining deployment in Deployment Designer. However, defining such constraints might prevent you from binding the application to a logical server that might otherwise support it when defining deployment.

For more information, see the following topics:

The following sections contain more information about application endpoints:

  • Endpoints on Applications

  • Adding Endpoints to Applications

  • Substituting Web Service Provider Endpoints

Endpoints on Applications

On an application, an endpoint is created from an abstract definition, such as a Web service, and can be either a "provider" or "consumer" endpoint. A provider endpoint identifies an addressable location at which a service is provided and represents the service as a small solid shape on the application shape. A consumer endpoint specifies the requirement for an application to use a service and represents the use of that service as a small hollow shape on the application shape. A consumer endpoint is configured with the address of the provider endpoint that offers the service being used and is typically connected to the provider endpoint. The shape, color, and icon displayed on an endpoint help identify and distinguish the endpoint type. On the application diagram, connections represent how to configure consumer endpoints in the development environment. On system diagrams, connections represent how to configure consumer endpoints at deployment.

For more information, see the following topics:

The following table describes predefined endpoint types that can appear on applications and whether they support implementation in the solution.

Application endpoint type Description

Database consumer endpoint

Represents a configurable connection point to a database.

A database consumer endpoint appears on an application when you connect the application with a database provider endpoint. A database consumer endpoint typically manifests itself in an implemented application as a specifically named database connection string in the application configuration file.

For more information, see How to: Configure Connections to External Databases.

Database provider endpoint

Represents an exposed connection point on a database.

A single database provider endpoint is included by default on an external database.

Generic consumer endpoint

Represents a connection point to a service of nonspecific type.

A generic consumer endpoint appears on an application when you connect the application with a generic provider endpoint.

Generic provider endpoint

Represents a connection point for services of nonspecific type. Included as a predefined prototype in the Toolbox.

A generic provider endpoint can be added to any application type.

Web content consumer endpoint

Represents a client connection point to Web content, such as HTML files or Active Server Pages (ASP).

A Web content consumer endpoint appears on an application when you connect the application with a Web content provider endpoint.

Web content provider endpoint

Represents a connection point at which Web content, such as HTML files or Active Server Pages (ASP), is exposed. Included as a predefined prototype in the Toolbox.

A Web content provider endpoint is included by default on an ASP.NET application created from the ASP.NETWebApplication prototype.

Web service consumer endpoint

Represents a connection point to a Web service.

A Web service consumer endpoint appears on an application when you connect the application to a Web service provider endpoint.

Web service provider endpoint

Represents a connection point for a Web service. Included as a predefined prototype in the Toolbox and can also be created by specifying a WSDL or .disco file.

A single Web service provider endpoint is included by default on an ASP.NET application created from the ASP.NETWebService prototype. Only a single Web service provider endpoint is ever present on any external Web service or BizTalk Web service application.

For more information, see Overview of ASP.NET Applications on Application Diagrams.

Adding Endpoints to Applications

Depending on the application prototype you choose and the type of application created from that prototype, an application that you add to the application diagram might have one, multiple, or no default endpoints. However, if needed, you can add provider endpoints to an application, depending on the endpoint type and whether the application type supports it, by dragging an endpoint prototype from the Toolbox to the application or copying and pasting other provider endpoints.

For example, the ASP.NETWebApplication prototype creates an ASP.NET application with a default Web content provider endpoint instead of a Web service provider endpoint. Dragging the WebServiceEndpoint prototype to the ASP.NET application creates a Web service provider endpoint on that application.

Tip

As a best practice for Web service endpoints, change the binding namespace from its default value ("https://tempuri.org").

You can add consumer endpoints to an application by connecting the application to provider endpoints on other applications or by copying and pasting other consumer endpoints. For example, Microsoft Windows and Office applications do not have default endpoints. However, connecting a Windows or Office application to an application that provides a service creates the appropriate consumer endpoint on that application.

You can also create prototypes from configured endpoints so that you can define new ones as well as extend the types of endpoints you can use. On ASP.NET applications, you can create Web service provider endpoints from WSDL or .disco files.

For more information, see How to: Add Endpoints to Applications, How to: Connect Applications on Application Diagrams, and How to: Create Custom Prototypes from Configured Applications and Endpoints.

Web Service Endpoints Created from WSDL or .disco Files

In Application Designer, Web service endpoint behavior is described using a hybrid representation of Web Services Description Language (WSDL) and the common language runtime (CLR). You can create a Web service provider endpoint on an ASP.NET application by specifying the location and name of a WSDL file or .disco file.

Note

Creating a Web service provider endpoint from a WSDL file produces a result equivalent to using the Wsdl.exe command line utility with the /server option. For more information, see Creating an XML Web Service Proxy and Web Services Description Language Tool (Wsdl.exe).

As a WSDL file specifies requirements for providing and consuming a Web service, the WSDL file acts as a contract between two applications and supports a contract-driven approach. Creating Web service provider endpoints from the same WSDL or .disco file also makes those endpoints substitutable. For more information, visit the Contract First Web Services Interoperability page on MSDN online at https://go.microsoft.com/fwlink/?LinkId=49584 and see Substituting Web Service Provider Endpoints.

Note

Only WSDL files containing single WSDL bindings and .disco files referencing single Web services are supported. For more information, see Communication Between Applications. However, multiple Web service provider endpoints can exist on an ASP.NET application, while only a single Web service provider endpoint can exist on an external Web service or BizTalk Web service. When you add an external Web service or BizTalk Web service to the application diagram, you are prompted to specify a WSDL file with only a single WSDL binding for that Web service. For more information, see How to: Locate WSDL Files for Web Services.

A Web service provider endpoint created from a WSDL or .disco file is populated with predefined operation signatures, including any references to common language runtime (CLR) classes that handle XML serialization for complex XML types as specified in the WSDL file or related XML schema files. If the application is implemented, these classes are added to the application project. If the application is not yet implemented, these classes are generated upon implementation.

Note

If you copy a Web service provider endpoint created from a WSDL or .disco file to another application, only the operation signatures are copied. If the destination application is already implemented, these classes will not be copied. If the target application is not yet implemented, these classes will not be generated. Therefore, it is recommended that you create these endpoints from the same WSDL or .disco file instead on the destination application.

In some XML schemas, additional serialization attributes are required on the Web service class and data serialization classes to make sure that the XML is formatted correctly. However, Web service provider endpoints created from WSDL files support only a small set of these serialization attributes. In a small number of cases, the resulting WSDL file generated for the Web service and the resulting XML messages might not be consistent with the original WSDL file used to create the Web service provider endpoint.

Tip

If you encounter such issues, you can use the Wsdl.exe utility to generate the Web service class and data serialization classes instead of using the functionality in Application Designer to create a Web service provider endpoint from a WSDL file. However, you will then need to manually add the generated code to your project and create the necessary .asmx file. A Web service provider endpoint will then appear correctly on the application diagram, making it possible for you to edit the endpoint using the designer.

The following list contains more information about support for these serialization attributes:

  • The following XML serialization attributes are added to classes generated for complex XML types: SerializableAttribute, SoapTypeAttribute, XmlIncludeAttribute, XmlRootAttribute, and XmlTypeAttribute.

  • The following XML serialization attributes are added to class fields: XmlAnyAttribute, XmlArrayAttribute, XmlArrayItemAttribute, XmlAttributeAttribute, XmlChoiceIdentifierAttribute, XmlElementAttribute, XmlEnumAttribute, XmlIgnoreAttribute, XmlNamespaceDeclarationsAttribute, and XmlTextAttribute.

  • Serialization attributes are not applied to the return type for Web methods.

  • Serialization attributes are not applied to the parameters of Web methods.

  • The following SOAP-encoded serialization attributes are not applied to these classes: SoapElementAttribute, SoapIgnoreAttribute, SoapAttributeAttribute, SoapAttributeOverrides, SoapAttributes, SoapEnumAttribute, and SoapIncludeAttribute.

  • Attribute arguments that require a complex XML type are generated as a String type with the fully qualified name of the type. This will cause a compiler error that will need to be fixed.

    For example, <XmlIncludeAttribute(GetType("ClassName"))> in Visual Basic is generated as <XmlIncludeAttribute("ClassName")>, while [XmlIncludeAttribute(typeof("ClassName"))] in Visual C# is generated as [XmlIncludeAttribute("ClassName")].

The WSDL binding definition in a WSDL file describes the operations exposed by the corresponding Web service. Creating a Web service provider endpoint in this manner represents the WSDL binding as a Web service provider endpoint and adds the operation signatures referenced by the WSDL or .disco file to the endpoint. Once an ASP.NET application with such an endpoint is implemented, the appropriate project files are generated for the Web service. For more information, see Overview of ASP.NET Applications on Application Diagrams.

For Web service consumer application that supports implementation, the WSDL file is used to generate the corresponding Web reference for that application upon implementation.

Note

Web references for consumer applications are generated only if WSDL file generation is enabled on an ASP.NET application. If enabled, a WSDL file is generated automatically for each of its Web services once the application is implemented. For more information, see How to: Control WSDL File Generation for ASP.NET Web Services.

Substituting Web Service Provider Endpoints

You can experiment with different Web service implementations, such as those supplied by third parties, by substituting one Web service endpoint for another as long as they are compatible with each other, for example, they have the same operations interface and can handle the same messages. By convention, the combination of a Web service's WSDL binding name and binding namespace identifies the behavior of the Web service. When you connect Web service endpoints in Application Designer and System Designer, the WSDL Binding Name and WSDL Binding Namespace properties on the endpoints determine whether the endpoints are compatible.

Note

A warning appears when connecting endpoints that do not have matching WSDL binding names or namespaces; however, such endpoints can still be connected. Even if the binding name and namespaces match between endpoints, there is no guarantee that the endpoints have compatible behavior, message schemas, or that their associated applications have correctly implemented their specification. It is recommended that you test the behavior of connected applications or risk discovering these incompatibilities at run time. For more information, see How to: Substitute Web Services on Application Diagrams.

After the WSDL file for a Web service has been published, each change made to the definition of a Web service is considered a new WSDL binding.

Tip

When changing the definition of a Web service, you should change the WSDL binding name, the WSDL binding namespace, or both. Changing a Web service definition without changing its WSDL binding name or namespace might hide the fact that the Web service is no longer compatible with connected or previously connected applications. The default value for the WSDL service name and the WSDL binding name is "WebServiceN" with "N" representing an ordinal number. However, once the application is implemented, deleting the WSDL binding name in the Web service class file changes the default value to "WebServiceNSoap". The default value for the WSDL service namespace and WSDL binding namespace is "https://tempuri.org". The WSDL service description and WSDL binding location properties do not have a default value. The default value for the WSDL binding name is "WebServiceN".

When you change the WSDL binding name or binding namespace on an unimplemented Web service provider endpoint, the corresponding properties of any connected and unimplemented consumer endpoints update automatically or when they are reconnected. However, when you change these properties on an implemented Web service provider endpoint, any connected and implemented Web service consumer endpoints might not update immediately. However, you can manually update these properties for these consumer endpoints.

See Also

Tasks

Walkthrough: Defining Applications

Other Resources

Constraining Application and Application Hosting Relationships
Defining Communication Pathways on Application Diagrams
Defining Endpoints on Applications