C# Dev Kit 常見問題集

Name: Visual Studio Code
Author: Microsoft

請使用此 FAQ（常見問題集）主題來深入了解 C# Dev Kit 擴充功能，並針對您可能遇到的問題進行疑難排解。

一般資訊

什麼是 C# Dev Kit？

C# Dev Kit 是為了增強您在 Visual Studio Code 中 C# 開發體驗而建立的擴充功能。它的目標是為 VS Code 帶來更廣泛、更具生產力且更可靠的 C# 體驗。C# Dev Kit 並不會取代現有的 C# 擴充功能，而是建立在它所提供的強大語言服務功能之上。開發人員可以選擇繼續使用已更新版本的現有 C# 擴充功能，或者透過新增 C# Dev Kit 來增強他們的體驗。

目前支援哪些專案類型？

C# Dev Kit 支援為 .NET Core（通常也稱為 .NET）建立 Web 應用程式、主控台應用程式、類別庫專案和測試專案。.NET MAUI 擴充功能和 Unity 擴充功能均建立在 C# Dev Kit 之上，並為建置 .NET 多平台應用程式 UI (MAUI) 和 Unity 應用程式提供額外支援。這些擴充功能支援現代 .NET 專案格式，也就是所謂的「SDK 風格」專案。如果您要建置非 SDK 格式的專案（例如 .NET Framework 應用程式和 Xamarin 應用程式），請參閱專案系統一節。

C# Dev Kit 中包含哪些擴充功能？

目前，C# Dev Kit 系列中包含的擴充功能有：

這些擴充功能的使用受 C# Dev Kit 擴充功能系列使用者授權合約 (EULA) 的規範。

這些擴充功能也有各自的授權相依項目，例如：C# Dev Kit 相依於 C# 擴充功能以及 .NET 安裝工具。

為什麼 C# Dev Kit 無法啟用 / 找不到 C# Dev Kit 命令？

當您嘗試編輯 C# 檔案時，C# Dev Kit 無法啟用的原因可能有幾種：

未安裝 2.0 版以上的 C# 擴充功能。C# Dev Kit 需要 C# 擴充功能 2.0 或更高版本。請確認您已安裝 C# 擴充功能，且版本為 2.0 或更高。
工作區偏好使用 C# 擴充功能。C# Dev Kit 不支援 .NET Framework 專案；如果您已將 dotnet.preferCSharpExtension 設定設為 true，C# Dev Kit 將在該工作區中停用。如果專案並非 .NET Framework 專案，請務必停用此設定。
使用唯讀作業系統。C# Dev Kit 需要寫入權限以存取其自身的擴充功能資料夾，以及 VS Code 提供的擴充功能資料夾，以便在作業系統內寫入任意狀態。因此，如果您使用的是完全唯讀的作業系統，C# Dev Kit 將無法運作。

如果您已檢查過上述項目但仍找不到 C# Dev Kit 命令，請回報問題並提供 C# Dev Kit「輸出」(Output) 視窗中的資訊。

授權與貢獻

誰可以使用 C# Dev Kit？

C# Dev Kit 可透過社群授權 (Community License) 提供給符合資格的使用者，它也被包含在現有的 Visual Studio 訂閱中。這意味著擁有有效 Visual Studio 訂閱的開發人員從今天起即可使用 C# Dev Kit。

對於個人、學術和開放原始碼專案，C# Dev Kit 可免費使用。針對商業用途，最多 5 人的小型團隊也可以免費使用 C# Dev Kit。對於 6 人以上的開發人員，這些使用者將需要 Visual Studio Professional（或更高階）訂閱。C# Dev Kit 也包含在 GitHub Codespaces 和 Microsoft Dev Box 中，因此這些產品的使用者無需額外付費即可存取 C# Dev Kit。

我該在哪裡提交意見反應與建議？

使用者可以透過 VS Code 的說明 > 回報問題 (Help > Report Issue) 來回報問題或提出建議。請選擇問題類型（錯誤、功能請求或效能問題）、檔案路徑選擇 An extension，並從擴充功能清單中選擇 C# Dev Kit。

Help > Report Issue image

C# Dev Kit 是開放原始碼嗎？為什麼不是？

不是。C# Dev Kit 是封閉原始碼，但它相依於開放原始碼的「C# for VS Code」擴充功能，且兩者皆與 Roslyn 和 Razor 等開放原始碼元件進行通訊。我們開發 C# Dev Kit 的目標之一，是為使用 VS Code 的 C# 開發人員提供更佳的生產力體驗。為了實現這一點，C# Dev Kit 包含了一些與我們其他工具共用的專屬封閉原始碼功能。為了將這些體驗提供給 VS Code 使用者，我們必須以封閉原始碼擴充功能的形式引入 C# Dev Kit。

我該如何貢獻？

作為 C# Dev Kit 一部分的 C# 擴充功能是完全開放原始碼的，並受這些授權條款規範。此擴充功能的原始程式碼位於 https://github.com/dotnet/vscode-csharp，並採用 MIT 授權。

本專案採用 Contributor Covenant 所定義的行為準則，以釐清我們社群中應有的行為。如需更多資訊，請參閱 .NET Foundation 行為準則。透過簽署 CLA，社群可以自由使用您對 .NET Foundation 專案的貢獻。

.NET SDK

安裝指令碼逾時

請注意，根據您的網路速度，安裝 .NET Core 執行階段可能需要一些時間。預設情況下，如果安裝時間超過 4.5 分鐘，安裝將會失敗並終止。如果您認為此時間不足（或過長），可以透過將 dotnetAcquisitionExtension.installTimeoutValue 設定為自訂值來變更逾時時間。

深入了解如何設定 VS Code 設定，並參考下方 settings.json 檔案中自訂逾時的範例。在此範例中，自訂逾時值為 180 秒（即 3 分鐘）。

{
  "dotnetAcquisitionExtension.installTimeoutValue": 180
}

取得 .NET SDK 時發生錯誤

Error acquiring .NET SDK

注意：如果您位於中國，您的 .NET SDK 下載可能會被封鎖並導致逾時。

您需要確保已安裝 .NET SDK。作為替代方案，您可以將 .NET 執行階段取得擴充功能指向現有的 .NET 安裝。

Point the .NET runtime acquisition extension to an existing .NET SDK install

我該如何手動安裝 .NET？

如果 .NET 安裝失敗，或者您想要重複使用現有的 .NET 安裝，可以使用 dotnetAcquisitionExtension.existingDotnetPath 設定。您可以從 C# Dev Kit 導覽 (Walkthrough) 或 .NET 網站手動安裝 .NET。若要將擴充功能指向該安裝位置，請依照下圖所示，以擴充功能 ID 和路徑更新您的設定。

Windows

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "C:\\Program Files\\dotnet\\dotnet.exe"
    }
  ]
}

macOS

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "/usr/local/share/dotnet/dotnet"
    }
  ]
}

擴充功能認為我離線（出現 400 或 407 錯誤回應），但我有使用代理伺服器

如果您的系統使用代理伺服器並停用了登錄存取權，您需要在擴充功能設定中明確設定代理伺服器 URL。當透過環境變數和登錄設定時，代理伺服器會自動偵測；但如果您的代理伺服器僅透過登錄機碼管理且登錄存取權被停用，擴充功能將無法找到它。若要設定代理伺服器 URL，請新增下方的擴充功能設定。

{
  "dotnetAcquisitionExtension.proxyUrl": "https://your_proxy_url:port"
}

專案系統

方案總管 (Solution Explorer) 回報我的專案在 C# Dev Kit 中不受支援

這通常是因為專案目標為 .NET Framework 而非 .NET Core/.NET。目前，C# Dev Kit 不支援 .NET Framework 專案。

Project Not Supported in Solution Explorer

若要解決此問題，您有兩種選擇：

您可以將您的專案更新為 SDK 風格的專案，以存取所有可用的 C# Dev Kit 功能。

或者，您可以使用「設定」編輯器中的偏好 C# 擴充功能 (Prefer CSharp Extension) 工作區設定，將專案和方案的載入委派給 C# 擴充功能。請記住，啟用此設定後，部分 C# Dev Kit 功能將無法使用。若要存取此設定，請前往「設定」編輯器並選擇工作區 (Workspace) 索引標籤。然後，在搜尋列中搜尋「Prefer CSharp」，並勾選偏好 C# 擴充功能設定旁邊的核取方塊。如果您嘗試載入 .NET Framework 專案，C# Dev Kit 會自動顯示通知，要求您將專案更新為 SDK 風格，或者透過選擇通知中的使用 C# 擴充功能 (Use C# Extension) 讓 C# 擴充功能載入您的專案或方案。此選項會自動選取「偏好 C# 擴充功能」設定。請注意，您需要重新載入 VS Code 才能使此設定生效。

我點擊了「建立 .NET 專案」按鈕，但沒有反應

這通常發生在擴充功能版本不符的情況下。C# Dev Kit 需要 C# 擴充功能 2.0 或更高版本。如果您使用的是 C# 擴充功能 v1，C# Dev Kit 和相關命令將無法正常運作。若要修正此問題，請將 C# 擴充功能升級至最新版本。

專案系統回報發生問題

當發生內部專案系統錯誤時，您通常會在 VS Code 的角落看到類似這樣的彈出通知。

Failed to Restore Solution

選擇開啟記錄 (Open log) 按鈕以開啟視窗，顯示發生問題的堆疊追蹤。選取並複製記錄中的所有文字。透過 VS Code 回報問題，並務必包含複製的記錄文字。

當我開啟方案時，收到「還原方案失敗」(Failed to restore solution) 的通知

選擇顯示錯誤 (Show error)。這會開啟 NuGet 的「輸出」面板。閱讀錯誤內容以確定套件還原無法完成的原因。如果您無法解決該問題，請透過 VS Code 回報。

方案總管顯示「找不到相容的 .NET SDK」(A compatible .NET SDK was not found)

此錯誤最可能的原因是 global.json 檔案指定的 SDK 與系統上安裝的 SDK 不同。

A compatible .NET SDK was not found

開啟「輸出」視窗並切換至專案 (Projects) 面板以查看更多資訊。您應該會看到類似這樣的內容：

Output Window Projects Pane

若要修正此問題，請更新 global.json 以指定已安裝的 SDK，或從下載 .NET 頁面安裝指定的 SDK。

接下來，關閉並重新開啟工作區。

也有可能是 SDK 的安裝位置不為 C# Dev Kit 所知。例如，如果 SDK 是透過套件管理員而非 Microsoft 提供的安裝程式安裝，就可能發生這種情況。若要修正此問題，請透過套件管理員解除安裝該 SDK，然後透過下載 .NET 進行安裝。

測試總管 (Test Explorer)

為什麼我的測試沒有出現在「測試總管」(Test Explorer) 面板中？

請確保您的方案包含測試專案。只有屬於開啟方案一部分的測試專案才會被包含在內。若要查看測試專案是否為方案的一部分，請開啟檔案總管中的「方案總管」，查看專案是否出現在樹狀結構中。在方案節點上按右鍵即可新增現有的測試專案，或在方案中建立新的測試專案。

C# Dev Kit 還要求必須成功建置您的專案，測試才會出現在「測試總管」面板中。此外，如果對您的專案/方案執行了清除 (Clean)，測試 dll 將會從「測試總管」面板中移除。

在確認測試專案已納入方案後，請在方案總管中對方案按右鍵並選擇建置 (Build)，或是使用 ⇧⌘B (Windows, Linux Ctrl+Shift+B)。建置完成後，您的測試就會出現在「測試總管」面板中。

如果測試仍未出現，請考慮進行下列額外檢查：

支援的 .NET Core SDK：確保您使用的是適用於您的平台和機器的支援 .NET Core SDK。部分 SDK 在特定作業系統或架構上無法運作。如需更多資訊，請查看官方 .NET 下載頁面：https://dotnet.microsoft.com/en-us/download。
有效的 SDK 安裝：驗證是否偵測到有效的 SDK 安裝。您可以啟用診斷記錄以檢查您的 .NET 專案偵測到了哪個 SDK。請注意，透過 ASDF 或 Mise 等不支援的工具安裝的 .NET SDK 可能無法被偵測到，因為它們背離了 Microsoft 的官方安裝方法。我們建議遵循官方說明。
建置輸出：確認建置已完成且已產生對應的輸出二進位檔，例如 .dll 或 .exe 檔案。
專案載入：確保所有專案皆已完成載入。在方案總管中，查看測試專案旁邊的測試圖示以確認它們已被偵測到。

我的測試出現在「測試總管」面板中，但我無法偵錯它們

請確保您的測試目標為 .NET Core。C# Dev Kit 不支援 .NET Framework 專案，儘管 .NET Framework 專案可能會載入並看起來可以運作。VS Code 中的偵錯工具不支援 .NET Framework。

我剛剛在測試專案中新增了新測試，但它們沒有出現在「測試總管」面板中？

C# Dev Kit 要求必須成功建置您的專案，測試才會出現在「測試總管」面板中。

請在方案總管中對方案按右鍵並選擇建置 (Build)，或是使用 ⇧⌘B (Windows, Linux Ctrl+Shift+B)。建置完成後，您的測試就會出現在「測試總管」面板中。

如何收集測試總管的疑難排解記錄？

如果您在使用測試總管時遇到問題，可以啟用診斷記錄以收集更多資訊以進行疑難排解：

提高測試總管的詳細程度：前往 C# Dev Kit 設定，將「測試總管詳細程度」(Test Explorer Verbosity) 設定從 minimal 提高至 diagnostic。這將會產生更詳細的記錄。
檢查「輸出」視窗：在 Visual Studio Code 中開啟「輸出」視窗，並從下拉式選單中選取 C# Dev Kit - Test Explorer。診斷訊息會顯示 [dev] 前綴。
收集下列資訊：回報問題時，請務必包含：
- 來自「輸出」視窗的診斷記錄。
- 您的作業系統及版本（例如：Windows 10、macOS 13）。
- 您使用的 C# Dev Kit 擴充功能版本。請前往「擴充功能」檢視，並將游標懸停在擴充功能上以查看版本資訊。

這些資訊有助於更有效率地診斷和解決問題。

偵錯工具

當我按 F5 時，沒有任何反應

請確保您已開啟 C# 專案，或目前的活動文件是 .cs 或 .razor 檔案。如果偵錯工具仍然無法載入，請確保 C# Dev Kit 和 C# 擴充功能皆已啟用。

當我按 F5 時，系統要求我「選擇偵錯工具」。我該如何知道要選擇哪一個？

如果您嘗試對 .NET 主控台應用程式、Blazor Server 應用程式、Blazor WebAssembly 或 Web 應用程式進行偵錯，請務必選擇 C# 選項。其他選項可能是其他擴充功能的一部分，例如用於 JavaScript 偵錯的 Node 或用於 Python 偵錯的 Python，它們不屬於 C# Dev Kit。

當我按 F5 時，系統提示我輸入密碼（僅限 macOS）

macOS 預設停用「開發人員模式」(Developer Mode)，如果程式想要作為偵錯工具使用，系統會提示輸入密碼以保護使用者。

如果您希望停用這些提示，可以執行下列命令：

DevToolsSecurity --enable
sudo dscl . append /Groups/_developer GroupMembership $USER

為什麼偵錯無法運作？

如果您嘗試對程式庫或測試專案進行偵錯，您很可能需要採取一些額外步驟，以確保程式碼被正確偵錯。若要對程式庫進行偵錯，您可以建立一個與該程式庫互動的主控台或 Web 應用程式。對於測試專案，您可以使用「測試總管」來有效地對程式碼進行偵錯。

偵錯時，我的中斷點未繫結

您正在偵錯的處理程序並未以 Debug 組態建置，請確保在對處理程序進行偵錯前先進行 Debug 建置。

C# 編輯器

如何讓 IntelliSense 正確運作？

請確保您已開啟專案或方案。如果您有多個方案，擴充功能會自動開啟一個，或提示您選擇開啟一個。接下來，在設定搜尋列中搜尋「Trace」，並將 Dotnet > Server: 從下拉式選單設為 Trace。此選項可提供更多輸出資訊，協助開發團隊診斷問題。

Set Dotnet Server to Trace

完成變更後，請透過開啟命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）、輸入「Reload Window」並按下 Enter 來重新載入視窗。視窗重新載入後，請檢查「輸出」面板（⇧⌘U (Windows Ctrl+Shift+U, Linux Ctrl+K Ctrl+H)）中的專案記錄，並從下拉式選單中選擇 Projects。這將顯示與您的專案未完全載入相關的任何錯誤。複製「輸出」面板中的所有文字並透過 VS Code 回報問題，並務必包含複製的文字。

C# 擴充功能無法啟動伺服器

作為替代方案，您可以使用 dotnetAcquisitionExtension.existingDotnetPath 設定將 .NET 執行階段取得擴充功能指向現有的 .NET 7 安裝。

{
  "dotnetAcquisitionExtension.existingDotnetPath": [
    {
      "extensionId": "msazuretools.azurerm-vscode-tools",
      "path": "C\\Program Files\\dotnet\\dotnet.exe"
    }
  ]
}

診斷訊息太多或太少

C# 擴充功能允許您設定各種背景程式碼分析設定。若要存取這些設定，請前往檔案 (File) > 喜好設定 (Preferences) > 設定 (Settings)，或使用鍵盤快速鍵（⌘, (Windows, Linux Ctrl+,)）。在搜尋列中輸入「analysis」以縮小與程式碼分析相關的設定範圍。在 Run background code analysis for: 下方，您可以從下拉式選單選擇分析範圍。預設設定為分析開啟的檔案，但您可以將其自訂為完整方案、無，或開啟的文件。

Configure Background Code Analysis

您也可以使用 EditorConfig 檔案來設定診斷和程式碼分析。若要深入了解 EditorConfig，請參閱相關文件。

如果您沒有看到足夠的診斷訊息，或根本沒看到，則可能是您的專案未完全載入。若要檢查是否為此情況，請參閱「如何讓 IntelliSense 正確運作？」一節，裡面提供了如何驗證專案是否已完全載入的說明。

Razor 編輯器

大多數或所有 Blazor 元件都顯示警告

在探索 Blazor 元件之前，C# Dev Kit 需要先成功載入您的專案。此外，Razor 語言伺服器需要產生 project.razor.vscode.bin 檔案，才能了解專案的狀態。如果未產生此檔案，或產生時未包含任何元件，Razor 的體驗可能會受到影響。

為了提升效能，擴充功能有時會延遲產生或載入此檔案，直到您開啟第一個 .razor 或 .cshtml 檔案為止。為了確保您要使用的專案在「方案總管」中沒有錯誤，請務必仔細檢查。

如果您的專案已正確載入，請確認檔案系統的 obj\Debug\<tfm> 資料夾中是否存在 project.razor.vscode.bin 檔案。由於它是二進位檔案，直接驗證其內容並不容易，但一般來說，大多數 Razor 專案產生的檔案大小至少應為 150KB。如果檔案只有幾 KB，則表示 Tag Helper 和/或元件可能未被正確偵測到。

若要強制重新產生檔案，請關閉任何已開啟的 .razor 或 .cshtml 檔案，重新載入 VS Code 視窗，並在專案正確載入後，開啟任何 .razor 或 .cshtml 檔案以觸發重新產生程序。

Razor 檔案中提到目標 Framework 錯誤

Razor 語言伺服器通常沒有「方案」的概念，而是根據專案 obj\Debug\<tfm> 資料夾中 project.razor.vscode.bin 檔案的存在與否來載入專案。有時，不再使用的目標 Framework 舊檔案可能會導致混淆，使 Razor 伺服器誤以為專案是多目標的，或誤以為某些元件仍被參考（即使它們已非如此）。

若要解決此問題，請清除 obj 資料夾中的舊資料夾，或全部清除。然後，重新載入 VS Code 視窗並開啟 .razor 檔案。這應能確保產生新的 JSON 檔案，並移除舊檔案。

IntelliCode

我無法獲得整行自動完成

當啟用 GitHub Copilot 擴充功能時，整行自動完成功能會被停用，以便您利用更先進的 AI 完成功能。您可以檢查 VS Code 右下角是否有 Copilot 標誌，以確認 Copilot 是否已啟用。

熱重新載入 (Hot Reload)

開始偵錯後，「熱重新載入」(Hot Reload) 圖示沒有出現

只有在 C# Dev Kit 偵錯工具設定中啟用了「熱重新載入」選項時，偵錯工具才會啟動「熱重新載入」工作階段。如果已啟用該選項，預期在偵錯時狀態列會出現「熱重新載入」圖示。

Hot Reload icon in the bottom bar

您可以點擊「熱重新載入」圖示，或開啟 C# 熱重新載入「輸出」視窗來查看診斷資訊。如果您沒看到上述任何內容，則該專案可能未受到 C# Dev Kit 擴充功能支援，請參閱「熱重新載入」支援的專案。

「熱重新載入」支援哪些類型的編輯？

請參閱支援的程式碼變更清單，了解「熱重新載入」支援的 C# 程式碼修改。

5/3/2024