萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 伺服器教學

解決 ASP.NET 升級至 3.5 後「asp:ScriptManager 標記不明確」錯誤

問題背景

老專案從 .NET Framework 2.0 升級至 3.5 時,原引用的 Microsoft ASP.NET 2.0 AJAX Extensions (System.Web.Extensions 1.0.61025.0) 與 3.5 內建的 System.Web.Extensions 3.5.0.0 衝突,導致兩類經典報錯:

  1. 類型不兼容: 基類包含欄位 "ScriptManager1",但其類型 (System.Web.UI.ScriptManager) 與控制項類型不兼容
  2. 標記不明確: 伺服器標記 "asp:ScriptManager" 不明確。請修改關聯註冊並選取新的標記前綴

根因分析

.NET 3.5 將 AJAX 內建為核心程式集 System.Web.Extensions 3.5.0.0,不再需要單獨安裝 AJAX Extensions 1.0。專案中殘留的 1.0 版本註冊(頁面 @Register、web.config)與 3.5 版本同時存在,導致編譯器無法確定 `asp:ScriptManager` 具體指向哪個版本。

分步解決方案(按優先級排序)

第一步:清理頁面級註冊指令

檢查所有 .aspx、.master、.ascx 頁面頂部,移除或更新舊版註冊:

<!-- ❌ 刪除或註釋掉舊版 1.0 註冊 -->
<%@ Register Assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" 
    Namespace="System.Web.UI" TagPrefix="asp" %>

<!-- ✅ 保留或添加 3.5 版本註冊(通常 3.5 專案模板已自動包含,無需手動添加) -->
<%@ Register Assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" 
    Namespace="System.Web.UI" TagPrefix="asp" %>

第二步:徹底重寫 web.config 組態區段(關鍵)

不要嘗試手動修改版本號,極易遺漏導致殘留衝突。建議備份後直接替換為標準 .NET 3.5 AJAX 組態區塊:

<configuration>
  <configSections>
    <sectionGroup name="system.web.extensions" type="System.Web.Configuration.SystemWebExtensionsSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
      <sectionGroup name="scripting" type="System.Web.Configuration.ScriptingSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
        <section name="scriptResourceHandler" type="System.Web.Configuration.ScriptingScriptResourceHandlerSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
        <sectionGroup name="webServices" type="System.Web.Configuration.ScriptingWebServicesSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
          <section name="jsonSerialization" type="System.Web.Configuration.ScriptingJsonSerializationSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="Everywhere" />
          <section name="profileService" type="System.Web.Configuration.ScriptingProfileServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication" />
          <section name="authenticationService" type="System.Web.Configuration.ScriptingAuthenticationServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication" />
          <section name="roleService" type="System.Web.Configuration.ScriptingRoleServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication" />
        </sectionGroup>
      </sectionGroup>
    </sectionGroup>
  </configSections>

  <system.web>
    <pages>
      <controls>
        <add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
        <add tagPrefix="asp" namespace="System.Web.UI.WebControls" assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      </controls>
    </pages>
    
    <!-- 僅當專案確實引用 1.0 版程式集時保留,純 3.5 專案可刪除 -->
    <assemblies>
      <add assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add assembly="System.Web.Extensions.Design, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    </assemblies>
    
    <httpHandlers>
      <remove verb="*" path="*.asmx"/>
      <add verb="*" path="*.asmx" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add verb="*" path="*_AppService.axd" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add verb="GET,HEAD" path="ScriptResource.axd" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" validate="false"/>
    </httpHandlers>
    
    <httpModules>
      <add name="ScriptModule" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    </httpModules>
  </system.web>

  <system.webServer> <!-- IIS 7+ 整合管線模式必需 -->
    <validation validateIntegratedModeConfiguration="false"/>
    <modules>
      <remove name="ScriptModule"/>
      <add name="ScriptModule" preCondition="managedHandler" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    </modules>
    <handlers>
      <remove name="WebServiceHandlerFactory-Integrated"/>
      <remove name="ScriptHandlerFactory"/>
      <remove name="ScriptHandlerFactoryAppServices"/>
      <remove name="ScriptResource"/>
      <add name="ScriptHandlerFactory" verb="*" path="*.asmx" preCondition="integratedMode" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add name="ScriptHandlerFactoryAppServices" verb="*" path="*_AppService.axd" preCondition="integratedMode" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add name="ScriptResource" verb="GET,HEAD" path="ScriptResource.axd" preCondition="integratedMode" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
    </handlers>
  </system.webServer>

  <system.web.extensions>
    <scripting>
      <webServices>
        <!-- 根據需求啟用服務 -->
        <authenticationService enabled="true" requireSSL="false"/>
        <profileService enabled="true" readAccessProperties="*" writeAccessProperties="*"/>
        <roleService enabled="true"/>
      </webServices>
    </scripting>
  </system.web.extensions>
</configuration>

第三步:清理解決方案引用與 Bin 目錄

  • 在 Visual Studio「方案總管」→「引用」中,移除 System.Web.Extensions (v1.0) 和 System.Web.Extensions.Design (v1.0)。
  • 檢查專案 Bin 目錄,刪除 System.Web.Extensions.dll (1.0 版本) 及其 .xml、.pdb 文件。.NET 3.5 運行時會自動從 GAC 載入 3.5 版本。

第四步:處理 SharePoint / 特殊環境(如適用)

若專案部署於 SharePoint,需在 web.config 的 <SharePoint>/<SafeControls> 中更新版本號:

<SafeControl Assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
    Namespace="System.Web.UI" TypeName="*" Safe="True" />

驗證清單

  1. 重新建置方案(Rebuild Solution),確認無編譯錯誤。
  2. 瀏覽包含 asp:ScriptManager 的頁面,確認無「標記不明確」錯誤。
  3. 檢查瀏覽器開發者工具 Network 面板,確認 ScriptResource.axd 正常載入(200 OK)。
  4. 測試 UpdatePanel、PageMethods、AJAX Control Toolkit 等核心功能。

避坑提示

  • 不要混合引用: 專案中絕對不能同時存在 1.0 和 3.5 版本的 System.Web.Extensions DLL。
  • Toolkit 版本對齊: 若使用 AJAX Control Toolkit,務必升級至對應 .NET 3.5 版本(如 v3.0.30930+)。
  • 機器.config 污染: 若伺服器層面 machine.config 殘留 1.0 組態,可能影響所有站點,建議在應用程式 web.config 中用 <remove> 覆蓋。
copyright © 萬盛學電腦網 all rights reserved