Considerations for Custom Web Service Client Proxy Classes
In Distributed System Designers, consumer endpoints on applications represent configurable connection points to provider endpoints. When an instance of a system definition composed from these applications is deployed, consumer endpoints on these applications are configured with the addresses of any connected provider endpoints. For more information, see Overview of Endpoints on Applications and Overview of Application Systems.
For Web service consumer endpoints, this requires the use of "dynamic" Web service client proxy classes that retrieve the URLs of connected Web service provider endpoints from the appropriate application configuration file entries at run time.
Note
For an application that supports implementation, Visual Studio generates a configuration file for that application when you implement it from the application diagram. The configuration file is included as part of the application project in Solution Explorer. For more information, see How to: Implement Applications on Application Diagrams.
By default, Application Designer generates Web references for these Web service consumer endpoints on ASP.NET, Windows, and Office applications. These Web references then create the appropriate dynamic proxy classes with the corresponding configuration file entries.
Note
If you use static Web references in an application or in a referenced class library, these Web references are not detected by Application Designer and are not visualized as Web service consumer endpoints, even though they might function correctly. It is recommended that you always use dynamic Web references, even if you do not intend for the Web service URL to change at deployment.
The following sections contain more information about using custom Web service client proxy classes instead of dynamic proxy classes:
Representing Custom Web Service Client Proxy Classes as Web Service Consumer Endpoints
Configuration File Entries for Custom Web Service Proxy Client Classes Used with Windows and Office Applications
Configuration File Entries for Custom Web Service Proxy Classes Used with ASP.NET Applications
Migrating Web References and Custom Proxy Classes from Visual Studio .NET 2003
Representing Custom Web Service Client Proxy Classes as Web Service Consumer Endpoints
Application Designer supports the design of Web service consumer endpoints that are implemented by Web references. However, you can also reverse-engineer and visualize manually created custom proxy classes as Web service consumer endpoints as long as the appropriate entries exist in the consumer application's configuration file (App.config or Web.config).
A Web service consumer endpoint appears on the consumer application for each configuration file entry that Application Designer identifies as representing a Web service URL setting for a custom proxy class. In addition, if the Web service URL in the configuration file entry matches the URL of an existing Web service provider endpoint on the application diagram, a connection appears between the consumer endpoint and the Web service provider endpoint. If no matching Web service provider endpoint exists, but the URL can be used to locate a valid WSDL file for the Web service by appending "?wsdl" or "?disco" to the URL, then an external Web service is added to the application diagram and is connected to the Web service consumer endpoint. If a WSDL file cannot be located using the URL, the Web service consumer endpoint remains unconnected.
The configuration file entries that represent Web service URL settings and the way that Application Designer identifies them differ between ASP.NET applications and Windows or Office applications. The following guidelines describe how you can ensure that custom proxy classes are represented correctly as Web service consumer endpoints on each type of application.
Note
Not following these guidelines might still produce custom proxy classes that function correctly at run time; however, these classes will not be represented as Web service consumer endpoints, will not be connected on the application diagram, will not be validated for deployment, will not be reported as endpoints on the deployment report, and will not be available for endpoint configuration using any available deployment tools.
Configuration File Entries for Custom Web Service Proxy Client Classes Used with Windows and Office Applications
For custom proxy classes used with Windows and Office applications, Web service URL settings must appear in an applicationSettings entry in the App.config configuration file of the consumer application. You cannot view or edit these settings using the Settings and Constraints Editor, so you must create or edit these settings using the Settings pane accessed by right-clicking the Windows or Office application project and viewing the project's properties. You must also designate these settings as WebServiceURL or String type. For more information, see Managing Application Settings.
Note
The WebServiceURL type designation does not appear in the App.config configuration file; however, it is stored in an associated settings file that is normally hidden. If you manually add the setting to the App.config configuration file, you must add the WebServiceURL or String type designation as a setting in the Settings pane.
In the Settings pane, you can choose Application or User scope for the setting if you designate it as WebServiceURL type. Changing the scope moves the entry to the applicationSettings or userSettings section in the configuration file. However, if you choose to designate the setting as a String type, you must choose Application for the scope.
Tip
When specifying a Web service URL setting in the App.config file, specify the location of the Web service, not the location of the Web service description or WSDL file. For .asmx file-based Web services, the Web service description is often at the same location as the WSDL location. Therefore, for .asmx file-based Web services, Application Designer will assume that the Web service location is the same as the WSDL file location. If a WSDL file is found at that location, an external Web service is reverse-engineered onto the application diagram and connected to a reverse-engineered Web service consumer endpoint. If a valid WSDL file is not found at that location, only the Web service consumer endpoint is reverse-engineered.
The following example shows how an applicationSettings entry might appear in an App.config configuration file of a Windows project when the setting is designated as String type:
<applicationSettings>
<WindowsApplicationName.MySettings>
<setting name="WindowsApplicationName_Namespace_WebServiceProxyClassName" serializeAs="String">
<value>http://WebServiceURL.asmx</value>
</setting>
</WindowsApplicationName.MySettings>
</applicationSettings>
For entries with WebServiceURL type, the name of the setting does not need to be the proxy class name. A configuration file entry that is defined in this way and is designated with the WebServiceURL or String type in the Settings pane is all that is required to create a Web service consumer endpoint on a Windows or Office application, even if no custom proxy class is associated with the entry. Deleting such an endpoint deletes the entry but does not delete the associated custom proxy class.
Configuration File Entries for Custom Web Service Proxy Classes Used with ASP.NET Applications
ASP.NET does not provide a way to specify that a configuration file entry represents a Web service URL. Therefore, Application Designer attempts to match the names of configuration file entries with proxy class names. The following guidelines apply to configuration file entries for custom proxy classes used with ASP.NET applications:
A Web service consumer endpoint appears only if a proxy class with a matching name is found in the consumer application project or in any referenced project or assembly.
If the custom proxy class is used only with ASP.NET applications, the Web service URL should appear in an appSettings entry in the ASP.NET application's Web.config configuration file. The name of the configuration file entry must be the fully qualified proxy class name. You can edit the appSettings entry in the Web.config file using the Settings and Constraints editor. For more information, see Settings and Constraints Editor and Applying Settings.
If the custom proxy class is used with Windows and Office applications as well as ASP.NET applications, the Web service URL should appear in an applicationSettings entry in the ASP.NET application's Web.config configuration file. The name of the configuration file entry must be the fully qualified proxy class name prefixed by the project name, which is the default format used by automatically generated Web references. You can edit the applicationSettings entry in the Web.config file using the Setting and Constraints editor. The applicationSettings section does not support dot (.) syntax for setting names; use underscore (_) characters instead.
The following example shows how an appSettings entry might appear in the Web.config file:
<appSettings>
<add key="Namespace.WebServiceProxyClassName" value="https://localhost/WebServiceApplicationName/WebServiceName.asmx"/>
</appSettings>
The following example shows how an applicationSettings entry might appear in the Web.config file, which is the same as the entry used in the App.config file of a Windows or Office application:
<applicationSettings>
<WindowsApplicationName.MySettings>
<setting name="WindowsApplicationName_Namespace_WebServiceProxyClassName" serializeAs="String">
<value>http://WebServiceURL.asmx</value>
</setting>
</WindowsApplicationName.MySettings>
</applicationSettings>
Deleting a Web service consumer endpoint that represents a custom proxy class removes the associated configuration file entry but does not delete the associated proxy class. Deleting or renaming the custom proxy class does not remove the associated configuration file entry; however, the corresponding consumer endpoint is removed because there is no longer a proxy class no longer with a matching name. Adding back a proxy class with a matching name or renaming an existing proxy class to match the configuration file entry causes the endpoint to reappear.
Migrating Web References and Custom Web Service Client Proxy Classes from Visual Studio .NET 2003
The associated configuration file entries for Web references that are added to Windows or Office projects using Visual Studio .NET 2003 are stored in an appSettings section instead of the applicationSettings section. When upgrading a Visual Studio .NET 2003 Windows or Office project using the conversion wizard, Web references and custom proxy classes do not migrate from the appSettings section to the applicationSettings section automatically. For more information about the conversion wizard, see Visual Studio Conversion Wizard.
However, Web references migrate automatically when proxy classes are regenerated, for example, when the corresponding Web services change or you manually refresh the Web reference. A new setting appears in the applicationSettings section for each Web reference and is used by the updated proxy classes. After the applicationSettings section is updated, the corresponding Web service consumer endpoints and connections appear on the application diagram. For more information, see How to: Refresh Web References to Web Services on Application Diagrams.
If you want to display Web service consumer endpoints for custom proxy classes, you must migrate these classes manually. You can perform this task by updating the proxy classes to use the applicationSettings section and adding the appropriate settings using the Settings pane available through the Windows or Office application project properties. For more information, see Managing Application Settings.
See Also
Concepts
Overview of Endpoints on Applications
Overview of ASP.NET Applications on Application Diagrams
Reference
Web References and Custom Web Service Client Proxy Classes in Class Libraries
Application Types and Prototypes for Defining Applications