.NET WebService 教程：从入门到实践

目录

1. 第一部分：什么是 WebService？

   
   （图片来源网络，侵删）
   • 1 核心概念
   • 2 为什么使用 WebService？
   • 3 主要技术标准：SOAP vs. REST

2. 第二部分：传统 .NET WebService (ASMX)

   • 1 ASMX 简介
   • 2 创建第一个 ASMX WebService
   • 3 测试 WebService
   • 4 创建客户端调用 ASMX WebService

3. 第三部分：现代 .NET WebService (ASP.NET Core Web API)

   • 1 Web API 简介 (为什么它是现代 WebService 的首选)
   • 2 创建第一个 ASP.NET Core Web API
   • 3 定义和实现 API 控制器与动作
   • 4 测试 Web API (使用 Swagger/OpenAPI)
   • 5 创建客户端调用 Web API

4. 第四部分：总结与对比

第一部分：什么是 WebService？

1 核心概念

WebService 是一种基于 Web 的、跨平台的、跨语言的远程服务调用技术，它允许不同的应用程序（无论使用何种编程语言或运行在何种操作系统上）通过标准的 Web 协议（主要是 HTTP）进行通信和交换数据。

你可以把它想象成一个“函数库”，但这个库部署在网络上，任何授权的程序都可以通过网络来调用它的函数并获取结果。

2 为什么使用 WebService？

• 跨平台和跨语言：WebService 使用 XML（或 JSON）作为数据格式，HTTP 作为传输协议，这些是所有现代平台和语言都支持的，实现了真正的“一次编写，到处运行”。
• 松耦合：客户端和服务端不需要了解对方的技术细节，只需通过事先约定好的接口（WSDL 或 API 文档）进行交互。
• 可复用性：一个核心业务逻辑（如用户验证、支付处理）可以被封装成 WebService，供多个不同的应用程序（网站、手机App、桌面软件等）共享使用。
• 分布式应用：WebService 是构建分布式系统的基础，可以将复杂的应用拆分为多个独立、可扩展的服务。

3 主要技术标准：SOAP vs. REST

在 .NET 世界里，创建 WebService 有两种主流范式：

.NET 对应技术：

• SOAP -> ASMX (较老，但仍在维护) 和 WCF (功能强大但复杂)。
• REST -> ASP.NET Web API (当前主流和推荐的选择)。

第二部分：传统 .NET WebService (ASMX)

ASMX 是 .NET Framework 中最早期、最简单的 WebService 实现，它非常容易上手，适合学习 WebService 的基本原理。

1 ASMX 简介

ASMX 服务本质上是继承自 System.Web.Services.WebService 的类，并通过特定的特性（Attribute）来标记哪些方法可以被客户端调用，它直接寄宿在 IIS 上。

2 创建第一个 ASMX WebService

前提条件：安装了 .NET Framework 和 Visual Studio (Community 版本即可)。

1. 创建项目

   • 打开 Visual Studio。
   • 选择 "创建新项目"。
   • 搜索并选择 "ASP.NET Web 应用程序"。
   • 给项目命名,AsmxWebServiceDemo。
   • 在弹出的模板窗口中,选择 "Web 服务" 模板，然后点击 "创建"。

2. 查看和修改代码

   • Visual Studio 会自动为你创建一个名为 Service.asmx 的文件，以及其背后的代码文件 Service.asmx.cs。
   • 打开 Service.asmx.cs，你会看到如下代码：

   using System.Web.Services;
   [WebService(Namespace = "http://tempuri.org/")]
   [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
   [System.ComponentModel.ToolboxItem(false)]
   // 若要允许使用 ASP.NET AJAX 从脚本调用此 Web 服务，请取消注释以下行。
   // [System.Web.Script.Services.ScriptService]
   public class Service : System.Web.Services.WebService
   {
       [WebMethod]
       public string HelloWorld()
       {
           return "Hello World";
       }
   }

   • 代码解释：
     • [WebService(...)]：标记这是一个 WebService 类。
     • [WebMethod]：这是最关键的特性，它标记了 HelloWorld 方法可以被远程客户端调用，没有这个特性的方法将无法被访问。

3. 添加自己的 WebMethod

   • 我们来添加一个更有用的方法,用于计算两个数的和。

   [WebMethod]
   public int Add(int a, int b)
   {
       return a + b;
   }

3 测试 WebService

1. 在 Visual Studio 中，按下 F5 或点击 "调试" -> "开始调试" 运行项目。

2. 浏览器会自动打开并显示 Service.asmx 的测试页面，你会看到 HelloWorld 和 Add 两个方法。

3. 点击 Add 链接，进入该方法的测试页面。

4. 在输入框中分别输入 10 和 20，然后点击 "调用" 按钮。

5. 页面下方会返回一个 XML 格式的结果，这正是 SOAP 响应的简化版。

   <?xml version="1.0" encoding="utf-8" ?>
   <int xmlns="http://tempuri.org/">30</int>

这个页面是 IIS 为 ASMX 服务自动生成的测试界面，非常方便。

4 创建客户端调用 ASMX WebService

最经典的方式是使用 Visual Studio 的 "添加 Web 引用" 功能。

1. 新建客户端项目

   • 在同一个解决方案中,新建一个 "控制台应用" 项目，命名为 AsmxClient。

2. 添加服务引用

   • 在 AsmxClient 项目上右键，选择 "添加" -> "服务引用..."。
   • 在弹出的窗口中,点击 "高级..."。
   • 在 "高级 Web 服务引用设置" 窗口中，点击 "添加 Web 引用..."。
   • 在 URL 输入框中，粘贴你的 ASMX 服务的地址（通常是 http://localhost:xxxx/Service.asmx），然后点击 "前往"。
   • 服务描述加载后,在 "Web 引用名" 中输入一个名字，MyService，然后点击 "添加引用"。

3. 调用服务

   • 打开 Program.cs，编写如下代码：

   using System;
   using AsmxClient.MyService; // 这是添加引用后自动生成的命名空间
   namespace AsmxClient
   {
       class Program
       {
           static void Main(string[] args)
           {
               // 1. 创建 WebService 代理类的实例
               Service service = new Service();
               // 2. 直接调用 WebMethod
               string helloResult = service.HelloWorld();
               Console.WriteLine("调用 HelloWorld 结果: " + helloResult);
               int sumResult = service.Add(15, 25);
               Console.WriteLine("调用 Add(15, 25) 结果: " + sumResult);
               Console.ReadKey();
           }
       }
   }

运行客户端程序,你将在控制台看到从 WebService 返回的结果。

第三部分：现代 .NET WebService (ASP.NET Core Web API)

我们学习当前更主流、更强大的方式：ASP.NET Core Web API，它遵循 RESTful 风格，性能更好，更灵活，并且是跨平台的。

1 Web API 简介

ASP.NET Core Web API 是一个框架，用于构建可以发送到 HTTP 客户端（如浏览器、手机、桌面应用）的 RESTful API，它不依赖于 IIS，可以运行在 Kestrel、Docker、Linux 等任何平台上。

2 创建第一个 ASP.NET Core Web API

前提条件：安装了 .NET SDK 和 Visual Studio (或 VS Code)。

1. 创建项目

   • 打开 Visual Studio。
   • 选择 "创建新项目"。
   • 搜索并选择 "ASP.NET Core Web API" 模板。
   • 给项目命名,WebApiDemo。
   • 确认选择了 "使用控制器...（推荐）" 的选项，然后点击 "创建"。

2. 了解项目结构

   • Controllers 文件夹：存放处理 HTTP 请求的控制器类。
   • Models 文件夹：存放数据模型类。
   • Program.cs：应用程序的入口点。
   • appsettings.json：配置文件。
   • 项目已经自带了一个示例 ValuesController。

3 定义和实现 API 控制器与动作

1. 创建数据模型

   • 在 Models 文件夹中，创建一个 Product.cs 类。

   // Models/Product.cs
   namespace WebApiDemo.Models
   {
       public class Product
       {
           public int Id { get; set; }
           public string Name { get; set; }
           public decimal Price { get; set; }
       }
   }

2. 创建 API 控制器

   • 在 Controllers 文件夹上右键，选择 "添加" -> "控制器..."。
   • 选择 "API 控制器 - 空"，然后点击 "添加"。
   • 将控制器命名为 ProductsController.cs。
   • 编写代码,实现对产品的 CRUD (增删改查) 操作。

   // Controllers/ProductsController.cs
   using Microsoft.AspNetCore.Mvc;
   using System.Collections.Generic;
   using WebApiDemo.Models;
   [ApiController] // 标记这是一个 API 控制器
   [Route("api/[controller]")] // 定义路由模板，/api/products
   public class ProductsController : ControllerBase
   {
       // 模拟一个数据库
       private static List<Product> _products = new List<Product>
       {
           new Product { Id = 1, Name = "笔记本电脑", Price = 5999 },
           new Product { Id = 2, Name = "无线鼠标", Price = 99 }
       };
       // GET: api/products
       [HttpGet]
       public ActionResult<IEnumerable<Product>> GetAllProducts()
       {
           return _products;
       }
       // GET api/products/5
       [HttpGet("{id}")]
       public ActionResult<Product> GetProduct(int id)
       {
           var product = _products.Find(p => p.Id == id);
           if (product == null)
           {
               return NotFound(); // 返回 404 Not Found
           }
           return product;
       }
       // POST api/products
       [HttpPost]
       public ActionResult<Product> CreateProduct(Product product)
       {
           product.Id = _products.Count + 1;
           _products.Add(product);
           // 返回 201 Created 状态码，并包含新创建资源的地址
           return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
       }
   }

   • 代码解释：
     • [ApiController]：提供一些有用的功能，比如自动模型验证。
     • [Route("api/[controller]")]：[controller] 是一个令牌，会自动被替换为控制器的名称（Products -> products）。
     • [HttpGet], [HttpPost]：指定 HTTP 方法。HttpGet 用于获取数据，HttpPost 用于创建数据。
     • ActionResult<T>：返回类型，可以返回不同的 HTTP 状态码（如 Ok(), NotFound(), CreatedAtAction()）。

4 测试 Web API (使用 Swagger/OpenAPI)

ASP.NET Core Web API 项目默认集成了 Swagger（现在叫 OpenAPI），这是一个强大的 API 文档和测试工具。

1. 运行项目
   • 按下 F5 运行项目。
2. 使用 Swagger UI
   • 浏览器会自动打开到 https://localhost:<port>/swagger。
   • 你会看到一个交互式的 API 文档页面，列出了你定义的所有端点。
   • 你可以展开每个端点,查看其参数和响应模型。
   • 点击 "Try it out" 按钮，填写参数，然后点击 "Execute"，直接在浏览器中测试你的 API！

5 创建客户端调用 Web API

现代客户端通常使用 HttpClient 来调用 REST API。

1. 创建客户端项目

   • 在同一个解决方案中,新建一个 "控制台应用" 项目，命名为 WebApiClient。
   • 在 WebApiClient 项目中，通过 NuGet 包管理器安装 Microsoft.AspNet.WebApi.Client 包。

2. 调用 API

   • 打开 Program.cs，编写代码来调用我们刚刚创建的 ProductsController。

   using System;
   using System.Collections.Generic;
   using System.Net.Http;
   using System.Net.Http.Headers;
   using System.Text.Json;
   using System.Threading.Tasks;
   using WebApiDemo.Models; // 确保客户端也有相同的模型类或使用 DTO
   // 为了方便，我们直接在客户端项目中复制一份 Product 模型
   // 在实际项目中，通常会使用共享的类库或生成客户端代码
   public class Product
   {
       public int Id { get; set; }
       public string Name { get; set; }
       public decimal Price { get; set; }
   }
   namespace WebApiClient
   {
       class Program
       {
           private static readonly HttpClient client = new HttpClient();
           static async Task Main(string[] args)
           {
               // 设置基础地址
               client.BaseAddress = new Uri("https://localhost:5001/");
               client.DefaultRequestHeaders.Accept.Clear();
               client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
               Console.WriteLine("1. 获取所有产品");
               await GetAllProductsAsync();
               Console.WriteLine("\n2. 创建一个新产品");
               var newProduct = new Product { Name = "机械键盘", Price = 399 };
               await CreateProductAsync(newProduct);
               Console.ReadKey();
           }
           private static async Task GetAllProductsAsync()
           {
               HttpResponseMessage response = await client.GetAsync("api/products");
               if (response.IsSuccessStatusCode)
               {
                   var content = await response.Content.ReadAsStringAsync();
                   var products = JsonSerializer.Deserialize<List<Product>>(content, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
                   foreach (var p in products)
                   {
                       Console.WriteLine($"ID: {p.Id}, Name: {p.Name}, Price: {p.Price}");
                   }
               }
               else
               {
                   Console.WriteLine($"Error: {response.StatusCode}");
               }
           }
           private static async Task CreateProductAsync(Product product)
           {
               var json = JsonSerializer.Serialize(product);
               var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
               HttpResponseMessage response = await client.PostAsync("api/products", content);
               if (response.IsSuccessStatusCode)
               {
                   Console.WriteLine("产品创建成功！");
                   var createdProduct = await response.Content.ReadFromJsonAsync<Product>();
                   Console.WriteLine($"新创建的产品: ID: {createdProduct.Id}, Name: {createdProduct.Name}");
               }
               else
               {
                   Console.WriteLine($"Error: {response.StatusCode}");
               }
           }
       }
   }

注意：在运行客户端之前，请确保 WebApiDemo 项目正在运行，由于 HTTPS 的存在，你可能需要在 WebApiDemo 项目的 Properties/launchSettings.json 中，将 WebApiClient 的 applicationUrl 添加到 WebApiDemo 的 launchBrowser 的 urls 列表中，或者在 WebApiClient 中处理 SSL 证书问题（开发环境下可以信任）。

第四部分：总结与对比

• 如果你正在维护一个古老的 .NET Framework 应用，并且需要与 ASMX 服务交互，那么你需要了解 ASMX。
• 如果你正在开发任何新的 .NET 应用程序，无论是 Web、移动端还是桌面应用的后端，ASP.NET Core Web API 都是毫无疑问的最佳选择，它更现代、更高效、更灵活，并且拥有庞大的社区支持和生态系统。

希望这份详细的教程能帮助你从零开始掌握 .NET WebService 的开发！