萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 呼叫 .NET WebService (ASMX) 完整實戰:SOAP 客戶端實作與常見坑點

前言

企業級系統整合常需 PHP 呼叫 .NET Framework 建立的 ASMX WebService(基於 SOAP 1.1/1.2 協議)。PHP 5 內建 SoapClient 提供原生支援,但實際整合常遇 WSDL 解析、型別對應、編碼、認證等問題。本文以實戰案例詳細說明完整整合流程。

.NET 端 WebService 範例 (C#)

// Localization.asmx.cs
using System.Web.Services;

[WebService(Namespace = "https://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class Localization : WebService
{
    [WebMethod]
    public string GetLocalizationResource(string culture = "zh-TW")
    {
        // 實際專案會從資源檔/資料庫讀取
        var resources = new Dictionary
        {
            ["Welcome"] = "歡迎使用系統",
            ["Login"] = "登入",
            ["Logout"] = "登出",
            ["Save"] = "儲存",
        };
        
        return Newtonsoft.Json.JsonConvert.SerializeObject(resources, 
            new Newtonsoft.Json.JsonSerializerSettings { 
                EnsureAscii = false 
            });
    }
}

PHP 端 SOAP 客戶端實作

基礎呼叫範例

<?php
// 關鍵:啟用 WSDL 快取提升效能
ini_set('soap.wsdl_cache_enabled', 1);
ini_set('soap.wsdl_cache_ttl', 3600); // 1 小時

try {
    $wsdlUrl = 'https://localhost/webservice1/Localization.asmx?wsdl';
    
    // 建立客戶端(生產環境建議關閉 WSDL 快取或設定較短 TTL)
    $client = new SoapClient($wsdlUrl, [
        'trace' => 1,                    // 除錯用:啟用請求/回應追蹤
        'exceptions' => true,            // 拋出 SoapFault 異常
        'cache_wsdl' => WSDL_CACHE_MEMORY,
        'features' => SOAP_SINGLE_ELEMENT_ARRAYS, // 避免單元素陣列變物件
        'encoding' => 'UTF-8',           // 強制 UTF-8
    ]);

    // 呼叫 WebMethod
    $result = $client->GetLocalizationResource(['culture' => 'zh-TW']);
    
    // .NET 回傳結構:$result->GetLocalizationResourceResult
    $jsonString = $result->GetLocalizationResourceResult;
    $resources = json_decode($jsonString, true);
    
    var_dump($resources);
    
} catch (SoapFault $fault) {
    // 詳細錯誤資訊
    error_log("SOAP Fault: {$fault->faultcode} - {$fault->faultstring}");
    if (isset($client)) {
        error_log("Last Request:\n" . $client->__getLastRequest());
        error_log("Last Response:\n" . $client->__getLastResponse());
    }
    // 回退機制或拋出業務異常
}
?>

進階:處理複雜型別與陣列

<?php
// .NET 端定義複雜型別
// public class UserProfile { public int Id; public string Name; public string[] Roles; }

// PHP 端對應:使用 stdClass 或關聯陣列
$params = [
    'userId' => 123,
    'profile' => [
        'Id' => 123,
        'Name' => '張三',
        'Roles' => ['Admin', 'Editor']  // 陣列自動序列化為 ArrayOfString
    ]
];

$result = $client->UpdateUserProfile($params);
// .NET 端接收:public void UpdateUserProfile(int userId, UserProfile profile)
?>

常見整合問題與解決方案

問題原因解決方案
WSDL 無法載入 / 連線逾時防火牆、網路不通、HTTPS 憑證驗證失敗1. 測試 curl $wsdlUrl 連通性
2. HTTPS 設定 'stream_context' => stream_context_create(['ssl' => ['verify_peer' => false, 'verify_peer_name' => false]])
ClassMap 對應失敗.NET 型別名稱含命名空間使用 'classmap' => ['{namespace}TypeName' => 'PHPClassName']
日期時間型別錯誤.NET DateTime ↔ PHP DateTime 格式不符傳遞 ISO 8601 字串:date('c') 或 DateTime::createFromFormat() 解析回傳值
長整數截斷 (int64)PHP 32 位元系統整數上限PHP 5.6+ 使用 gmp 或字串傳遞;.NET 端改用 long 對應 string
編碼亂碼雙端編碼不一致雙端強制 UTF-8,PHP 設定 'encoding' => 'UTF-8'
SOAP Header 認證失敗.NET 端要求 SOAP Header 驗證使用 SoapHeader 注入認證 Token

SOAP Header 認證實作

<?php
$authHeader = new SoapHeader(
    'https://tempuri.org/',           // 命名空間需與 .NET 端一致
    'AuthToken',                     // Header 元素名
    ['Username' => 'api_user', 'Password' => 'secret123'], // 複雜型別
    false                            // mustUnderstand
);

$client->__setSoapHeaders([$authHeader]);

$result = $client->GetProtectedData();
?>

效能優化與生產環境建議

  • WSDL 快取:生產環境設定 ini_set('soap.wsdl_cache_enabled', 1); ini_set('soap.wsdl_cache_ttl', 86400); 避免每次請求下載 WSDL
  • 連線複用:使用單例模式複用 SoapClient 實例(注意執行緒安全)
  • 錯誤重試:實作指數退避重試機制(網路抖動常見)
  • 監控告警:記錄呼叫延遲、失敗率、回應大小
  • 替代方案:新專案建議改用 RESTful API + JSON,避開 SOAP 複雜度

除錯技巧

<?php
// 開啟追蹤後,可輸出原始 XML 請求/回應
$client = new SoapClient($wsdl, ['trace' => 1, 'exceptions' => 0]);
$result = $client->SomeMethod($params);

echo "<h3>Request</h3><pre>". htmlspecialchars($client->__getLastRequest()) ."</pre>";
echo "<h3>Response</h3><pre>". htmlspecialchars($client->__getLastResponse()) ."</pre>";
echo "<h3>Request Headers</h3><pre>". htmlspecialchars($client->__getLastRequestHeaders()) ."</pre>";
echo "<h3>Response Headers</h3><pre>". htmlspecialchars($client->__getLastResponseHeaders()) ."</pre>";
?>

總結

PHP 呼叫 .NET ASMX WebService 核心在於:正確配置 SoapClient 參數、處理型別對應、解決編碼與認證問題。本文提供從基礎呼叫到進階除錯的完整指南。雖然 SOAP/ASMX 屬傳統技術,但在存量系統整合中仍不可避免,掌握這些技巧能大幅降低整合風險。

copyright © 萬盛學電腦網 all rights reserved