Overview of ASP.NET Applications on Application Diagrams
In Application Designer, you can define ASP.NET applications that expose .asmx file-based Web services, document Web content, or both by adding or using the appropriate endpoints. When you add an ASP.NET Web service application or an ASP.NET Web application to the application diagram, the application definition has a default Web service or Web content provider endpoint, respectively. However, you can add or remove provider endpoints of either type on an ASP.NET application. You can also substitute Web service provider endpoints on ASP.NET applications.
For more information, see the following topics:
The following sections contain more information about ASP.NET applications on the application diagram:
Defining Web Services on ASP.NET Applications
Defining ASP.NET Web Applications
Implementing ASP.NET Applications
Implementing Web Service Consumer Applications
Defining Web Services on ASP.NET Applications
A Web service on an ASP.NET application is represented by a Web service provider endpoint. A Web service consumer endpoint on any application represents a connection point to a Web service. You can define, review, and edit operations for Web services on ASP.NET applications.
Defining, Reviewing, and Editing Operations
In Application Designer, you can define, view, and edit operations and parameters for each Web service on an ASP.NET application through its corresponding Web service provider endpoint.
Tip
Application Designer also supports a contract-driven approach in that you can create a Web service provider endpoint on an ASP.NET application with predefined operation signatures and types based on an existing WSDL file or .disco file. For more information, see Web Service Endpoints Based on WSDL Files.
You can define one or more operations using the following elements:
Operation name and return type, if appropriate.
Operation parameters, including their names, types if appropriate, and modifiers describing how to pass each parameter.
Optional comments for each operation or parameter.
For more information, see How to: Define Operations for ASP.NET Web Services.
Defining Operations in the Web Service Details Window
In Application Designer, you can use the Web Service Details window to define, view, or edit operations for a Web service provider endpoint on an ASP.NET application. For Web services on implemented ASP.NET applications, this window shows Web service operations correctly only when the corresponding Web methods are fully declared within a single class definition in a separate code file or "code-behind" file.
The following table describes scenarios when the Web Service Details window does not show Web service operations correctly.
Scenario |
Web Service Details window |
|---|---|
The .asmx file contains the Web service class definition inline. |
Does not show any operations. |
Web methods that are declared by attributes on the methods of an interface implemented by a Web service class. -or- A class extends a base class that defines Web methods. |
Shows only those operations corresponding to the Web methods declared in the class referenced by the .asmx file. |
Code-behind files that define Web services containing multiple bindings. |
Shows only those operations associated with the first binding. |
For more information, see Considerations for Reverse-Engineering in Existing Solutions.
Referencing Types for Operations and Parameters
Referencing a type for an operation or parameter is appropriate depending on the programming language chosen for the application. When defining an operation or parameter, you can choose one of the following actions:
Leave the type as empty or set to the default as appropriate.
Choose a type from the IntelliSense type list.
Reference a type defined in other type libraries and projects, if a reference to those libraries or projects exist in the application project.
Reference a type you plan to define at a later time.
When you define operations and parameters using the Web Service Details window, IntelliSense support is available for referencing types for Visual Basic and Visual C#. Once the application is implemented, you can define new types or redefine existing types. For more information, see How to: Define Operation and Parameter Types for ASP.NET Web Services.
Defining ASP.NET Web Applications
In Application Designer, a Web content provider endpoint on an ASP.NET application represents a connection point at which Web content is exposed, for example, HTML files or Active Server Pages (.aspx files). A Web content consumer endpoint on any application represents a client connection point to Web content.
Web content endpoints do not support code generation or synchronization, nor do they generate and synchronize with application configuration (.config) file entries. However, you can use these endpoints to document requirements and set constraints on Web content support for a Web site hosted on a Web server.
For more information, see the following topics:
Implementing ASP.NET Applications
When you implement an ASP.NET application, Visual Studio generates the corresponding project with the appropriate project files. You can implement ASP.NET applications as ASP.NET Development Server Web projects (file system-based) or as Internet Information Services (IIS) Web projects (HTTP-based). For more information, see Application Types and Prototypes for Defining Applications and How to: Choose Web Site Type for ASP.NET Applications.
All ASP.NET application projects include a Web.config configuration file as part of the root project in Solution Explorer. For an ASP.NET application with one or more Web service provider endpoints, the project also includes an .asmx file and a Web service class file, which is a programming language-specific code file or "code-behind file", for each Web service provider endpoint.
In the Web service class, a WSDL binding with a single binding and a single port is associated with each Web service provider endpoint. Each Web service operation, along with any comments, appears as a method labeled with the WebMethod attribute in the Web service class. For any Web service provider endpoints created from a WSDL or .disco file, class files defining any complex XML types that support XML serialization for operations in the WSDL file or related XML schema files are also included in the application project. You can then complete implementation of each operation by adding the necessary method body code. For more information, see Web Service Endpoints Based on WSDL Files.
Note
Any WSDL descriptions that you specify in operation comments also appear in the WSDL file. You can also customize generation of the WSDL file. For more information, see WSDL File Generation for ASP.NET Web Services.
While the source code for an implemented application is considered the master definition, changes that you make to an ASP.NET Web service in Application Designer, the Web Service Details window, or a code editor synchronize with each other when the application diagram is open. However, a closed diagram will synchronize with changes to the code the next time the diagram opens. For more information, see How to: Implement Applications on Application Diagrams.
Dynamic Port Assignments for ASP.NET Web Applications
Upon implementing a file system-based ASP.NET application, which generates an ASP.NET Development Server Web project, a port number is assigned to the associated Web site. As file system-based ASP.NET applications are set to use dynamic ports by default, this port number can change.
Tip
You can view the port number in the Properties window by right-clicking the ASP.NET application project in Solution Explorer.
For example, new port numbers are assigned to file system-based ASP.NET applications under any of the following conditions:
When opening a solution containing these types of ASP.NET applications as well as implemented Web service consumer applications with references to Web services exposed by these ASP.NET applications.
When using the Visual Studio Debugger for the first time in a solution containing these types of ASP.NET applications.
If the associated Web service consumer application projects are in the same solution, they are updated automatically. However, if they are not in the same solution, for example, if they are in partitioned solutions, their Web references will not be updated and point to nonexistent Web services.
Note
If you are using source code control, and the associated Web service consumer application projects are checked into source code control, you must check out those projects to update the Web references.
To control the assignment of port numbers, you can set the project of a file system-based ASP.NET application to not use dynamic ports.
Note
After specifying not to use dynamic ports, starting the Visual Studio Debugger might generate an error that the existing port is in use. In this case, you must change the port number manually for the Web site project. When you change the port number, Visual Studio generates a warning that existing Web references will become invalid. If the application diagram is open, the Web references are updated. However, if the application diagram is not open, you must delete and then add back those Web references.
For more information, see the following topics:
Implementing Web Service Consumer Applications
When you implement an application with one or more Web service consumer endpoints, a Web reference is generated for each Web service consumer endpoint, if the WSDL file used to generate the Web reference is available. This WSDL file is specified by the WSDL location property on the Web service consumer endpoint. When the Web reference is generated, the Web service URL in the consumer application's configuration file is also generated.
Note
If a connected ASP.NET Web service provider application is implemented at the same time, the WSDL file will be available during implementation. However, if the connected Web service provider application is not implemented when the consumer endpoint is implemented, the consumer endpoint displays a warning indicating that the consumer endpoint could not be implemented. When a Web service provider application is implemented, any connected consumer endpoints are implemented automatically if the consumer application is implemented. For more information, see Troubleshooting Application Diagrams.
The Web reference handles creating the Web service client proxy class and proxy types for calling Web service operations and handling the communication of SOAP messages. You can also reverse-engineer and visualize custom Web service client proxy classes, including those custom proxy classes and Web references defined in class libraries, as Web service consumer endpoints. For more information, see Creating an XML Web Service Proxy and Considerations for Custom Web Service Client Proxy Classes.
Note
You can also enable XML documentation for a Windows or Web service consumer application after implementation to include operation comments in an XML file. This file is generated after you build the application project. To generate the XML file, you must enable XML documentation for the Windows project. For Visual Basic Windows projects, see How to: Generate XML Documentation for a Project. For Visual C# Windows projects, see How to: Set Build Properties (C#) and Build Page, Project Designer (C#).