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.

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.

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="http://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.

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.

Concepts

Reference

Other Resources