編輯

C# 開發工具包常見問題解答

Name: Visual Studio Code
Author: Microsoft

使用本常見問題解答 (FAQ) 主題來詳細瞭解 C# 開發工具包擴充套件，並對可能遇到的問題進行故障排除。

通用

什麼是 C# 開發工具包？

C# 開發工具包是一個為增強 Visual Studio Code 中的 C# 開發體驗而建立的擴充套件。它旨在為 VS Code 帶來更廣闊、更高效、更可靠的 C# 體驗。C# 開發工具包不會取代現有的 C# 擴充套件，而是在其提供的出色語言服務功能之上進行補充。開發者可以選擇繼續使用現有 C# 擴充套件的更新版本，或者透過新增 C# 開發工具包來增強他們的體驗。

目前支援哪些專案型別？

C# 開發工具包支援為 .NET Core（通常也稱為 .NET）構建 Web 應用、控制檯應用、類庫專案和測試專案。.NET MAUI 擴充套件和Unity 擴充套件構建在 C# 開發工具包之上，為構建 .NET 多平臺應用 UI (MAUI) 應用和 Unity 應用提供了額外支援。這些擴充套件支援現代 .NET 專案格式，也稱為“SDK 風格”專案。如果你正在構建非 SDK 格式的專案，例如 .NET Framework 應用和 Xamarin 應用，請參閱專案系統部分。

C# 開發工具包中包含哪些擴充套件？

目前，C# 開發工具包系列中包含的擴充套件有：

這些擴充套件的使用受C# 開發工具包系列擴充套件終端使用者許可協議 (EULA) 的約束。

這些擴充套件還有一些依賴項，它們帶有自己的許可證——例如，C# 開發工具包依賴於C# 擴充套件和.NET 安裝工具。

為什麼 C# 開發工具包沒有啟用/找不到 C# 開發工具包的命令？

當你嘗試編輯 C# 檔案時，C# 開發工具包沒有啟用，可能有以下幾個原因。

未安裝 2.0+ 版本的 C# 擴充套件。C# 開發工具包需要 2.0 或更高版本的 C# 擴充套件。請檢查確保你已安裝 C# 擴充套件，並且版本為 2.0 或更高。
工作區偏好使用 C# 擴充套件。C# 開發工具包不支援 .NET Framework 專案，如果你已將 dotnet.preferCSharpExtension 設定為 true，則 C# 開發工具包將對該工作區停用。如果專案不是 .NET Framework 專案，請確保停用此設定。
使用只讀作業系統。C# 開發工具包需要對其自身的擴充套件資料夾以及 VS Code 提供的用於擴充套件寫入任意狀態的資料夾具有寫入許可權，因此，如果你使用的是完全只讀的作業系統，C# 開發工具包將無法工作。

如果你已經檢查了這些問題，但仍然找不到 C# 開發工具包的命令，請報告問題並提供 C# 開發工具包輸出視窗中的資訊。

許可和貢獻

誰可以使用 C# 開發工具包？

C# 開發工具包透過社群許可證提供給符合條件的個人，並且也作為對現有 Visual Studio 訂閱的又一補充。這意味著擁有有效 Visual Studio 訂閱的開發者今天就可以使用 C# 開發工具包。

對於個人、學術和開源專案，C# 開發工具包可以免費使用。對於商業用途，最多 5 人的團隊也可以免費使用 C# 開發工具包。對於 6 人及以上的開發者，這些使用者將需要 Visual Studio Professional（或更高版本）訂閱。C# 開發工具包也包含在 GitHub Codespaces 和 Microsoft Dev Box 中，因此這些產品的使用者可以免費使用 C# 開發工具包，無需額外費用。

我應該在哪裡提交反饋和建議？

使用者可以透過 VS Code 的**幫助 > 報告問題**來報告問題或建議。選擇是錯誤、功能請求還是效能問題，提交到**一個擴充套件**，然後從擴充套件列表中選擇 **C# Dev Kit**。

Help > Report Issue image

C# 開發工具包是開源的嗎？為什麼不是？

不是。C# 開發工具包是閉源的，但它依賴於開源的 C# for VS Code 擴充套件，並且兩者都與開源元件（如 Roslyn 和 Razor）進行通訊。我們 C# 開發工具包的目標之一是為使用 VS Code 的 C# 開發者提供改進的生產力體驗。為了實現這一點，C# 開發工具包包含了一些與我們其他工具共享的專有、閉源功能。為了讓 VS Code 使用者也能使用這些體驗，我們需要將 C# 開發工具包作為一個閉源擴充套件引入。

我如何做出貢獻？

C# 擴充套件是 C# 開發工具包的一部分，它是完全開源的，並受這些許可條款的約束。該擴充套件的原始碼可在 https://github.com/dotnet/vscode-csharp 上找到，並根據 MIT 許可證授權。

本專案採用了貢獻者契約定義的行為準則，以明確我們社群中的預期行為。更多資訊，請參閱 .NET 基金會行為準則。透過簽署 CLA，社群可以自由地使用你對 .NET 基金會專案的貢獻。

.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 設定。.NET 可以從 **C# 開發工具包演練**或 .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"
}

專案系統

解決方案資源管理器報告我的專案在 C# 開發工具包中不受支援

這通常是因為專案面向的是 .NET Framework 而不是 .NET Core/.NET。目前，C# 開發工具包不支援 .NET Framework 專案。

Project Not Supported in Solution Explorer

要解決此問題，你有兩種選擇。

你可以將你的專案更新為 SDK 風格的專案，以訪問所有可用的 C# 開發工具包功能。

或者，你可以在設定編輯器中使用**偏好 CSharp 擴充套件**工作區設定，將專案和解決方案的載入委託給C# 擴充套件。請記住，使用此設定後，某些 C# 開發工具包功能將不可用。要訪問此設定，請轉到設定編輯器並選擇**工作區**選項卡。然後，在搜尋欄中搜索“Prefer CSharp”，並勾選**偏好 CSharp 擴充套件**設定旁邊的複選框。如果你嘗試載入 .NET Framework 專案，C# 開發工具包將自動顯示一個通知，要求你將專案更新為 SDK 風格的專案，或者透過從通知中選擇**使用 C# 擴充套件**來讓 C# 擴充套件載入你的專案或解決方案。此選項將自動選擇**偏好 CSharp 擴充套件**設定。請注意，你需要重新載入 VS Code 才能使此設定生效。

我點選了“建立 .NET 專案”按鈕，但沒有任何反應

這通常發生在擴充套件版本不匹配時。C# 開發工具包需要 2.0 或更高版本的C# 擴充套件。如果你使用的是 v1 版本的 C# 擴充套件，C# 開發工具包以及與 C# 開發工具包相關的命令將無法正常工作。要解決此問題，請將 C# 擴充套件升級到最新版本。

專案系統報告它遇到了問題

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

Failed to Restore Solution

選擇**開啟日誌**按鈕，開啟一個檢視，顯示問題發生處的堆疊跟蹤。選擇並複製日誌中的所有文字。透過 VS Code 報告問題，並確保包含從日誌中複製的文字。

當我開啟我的解決方案時，我收到通知“未能還原解決方案”

選擇**顯示錯誤**。這將開啟 NuGet 的輸出面板。通讀錯誤資訊，以確定包還原無法完成的原因。如果你無法解決問題，請透過 VS Code 報告問題。

解決方案資源管理器顯示“未找到相容的 .NET SDK”

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

A compatible .NET SDK was not found

開啟輸出視窗並切換到**專案**窗格以查詢更多資訊。你應該會看到類似這樣的內容

Output Window Projects Pane

要解決此問題，請更新 global.json 以指定一個已安裝的 SDK，或從下載 .NET 頁面安裝指定的 SDK。

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

也可能是 SDK 沒有安裝在 C# 開發工具包已知的位置。例如，如果 SDK 是透過包管理器而不是透過微軟提供的安裝程式安裝的，就可能發生這種情況。要解決此問題，請透過包管理器解除安裝 SDK，然後透過下載 .NET 進行安裝。

測試資源管理器

為什麼我的測試沒有出現在測試資源管理器面板中？

確保你的解決方案包含一個測試專案。只有作為已開啟解決方案一部分的測試專案才會被包含。要檢視測試專案是否是解決方案的一部分，請在檔案資源管理器中開啟解決方案資源管理器檢視，並檢視專案是否出現在樹中。右鍵單擊解決方案節點以新增現有測試專案，或在解決方案中建立新的測試專案。

C# 開發工具包還要求在測試出現在測試資源管理器面板之前，它已經成功構建了你的專案。此外，如果對你的專案/解決方案執行了**清理**操作，測試 dll 會從測試資源管理器面板中移除。

在確認你的測試專案是解決方案的一部分後，透過在解決方案資源管理器中右鍵單擊解決方案並選擇**生成**，或使用 ⇧⌘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 可能無法被檢測到，因為它們偏離了微軟的官方安裝方法。我們建議遵循官方說明。
生成輸出：確認生成已完成並已生成相應的輸出二進位制檔案，例如 .dll 或 .exe 檔案。
專案載入：確保所有專案都已載入完畢。在解決方案資源管理器中，查詢測試專案旁邊的測試圖示，以確認它們已被檢測到。

我的測試出現在測試資源管理器面板中，但我無法除錯它們

確保你的測試面向的是 .NET Core。C# 開發工具包不支援 .NET Framework 專案，儘管 .NET Framework 專案可能會載入並看起來可以工作。VS Code 中的偵錯程式不支援 .NET Framework。

我剛剛向我的測試專案添加了新測試，但它們沒有出現在測試資源管理器面板中？

C# 開發工具包要求在測試出現在測試資源管理器面板之前，它已經成功構建了你的專案。

透過在解決方案資源管理器中右鍵單擊解決方案並選擇**生成**，或使用 ⇧⌘B (Windows、Linux 為 Ctrl+Shift+B) 來構建你的解決方案。構建完成後，你的測試將出現在測試資源管理器面板中。

為什麼我的測試在測試資源管理器中沒有被發現或執行？

如果你的測試專案正在使用 Microsoft 測試平臺 (MTP)（無論是透過 MSTest、NUnit、xUnit v3 還是 TUnit 測試框架），你的測試可能無法在測試資源管理器中被發現或執行，因為 MTP 與傳統的 VSTest 平臺不同。要解決此問題，你需要在 Visual Studio Code 中啟用“使用測試平臺協議”設定，以允許 C# 開發工具包與 MTP 測試專案通訊。

請按照以下步驟啟用該設定：

在 VS Code 中開啟設定：轉到檔案 > 首選項 > 設定（或按 ⌘, (Windows、Linux 為 Ctrl+,)）。
在設定搜尋欄中，輸入“Test Window”以篩選結果。
在 C# 開發工具包擴充套件設定下，找到設定 Dotnet > Test Window: Use Testing Platform Protocol。
勾選複選框以啟用它（或將其切換為“開”）。
透過在命令面板（⇧⌘P (Windows、Linux 為 Ctrl+Shift+P)）中執行**重新載入視窗**命令來重新載入 VS Code。

啟用此設定後，你的測試應該可以在測試資源管理器中被正確發現和執行。

如何收集用於排查測試資源管理器問題的日誌？

如果你遇到測試資源管理器的問題，可以啟用診斷日誌以收集更多資訊進行故障排除：

增加測試資源管理器的詳細程度：導航到 C# 開發工具包設定，並將測試資源管理器詳細程度設定從 `minimal` 增加到 `diagnostic`。這將生成更詳細的日誌。
檢查輸出視窗：在 Visual Studio Code 中開啟輸出視窗，並從下拉選單中選擇 **C# Dev Kit - Test Explorer**。診斷訊息將以 `[dev]` 前綴出現。
收集以下資訊：報告問題時，請確保包含：
- 來自輸出視窗的診斷日誌。
- 你的作業系統和版本（例如，Windows 10、macOS 13）。
- 你正在使用的 C# 開發工具包擴充套件的版本。轉到擴充套件檢視，並將滑鼠懸停在擴充套件上以檢視版本資訊。

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

偵錯程式

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

確保你已開啟一個 C# 專案，或者活動文件是 .cs 或 .razor 檔案。如果偵錯程式仍然無法載入，請確保 C# 開發工具包和 C# 擴充套件都已啟用。

當我按 F5 時，它要求我“選擇一個偵錯程式”。我該如何知道選擇哪一個？

如果你正在嘗試除錯 .NET 控制檯應用程式、Blazor 伺服器應用、Blazor WebAssembly 或 Web 應用程式，請確保選擇 **C#** 選項。其他選項可能是其他擴充套件的一部分，例如用於 JavaScript 除錯的 **Node** 或用於 Python 除錯的 **Python**，它們不屬於 C# 開發工具包。

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

macOS 預設停用開發者模式，如果某個程式想用作偵錯程式，它會提示輸入密碼以保護使用者。

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

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

為什麼除錯不工作？

如果你正在嘗試除錯一個庫或一個測試專案，很可能需要採取一些額外的步驟來確保你的程式碼被正確除錯。要除錯一個庫，你可以建立一個與該庫互動的控制檯或 Web 應用程式。對於測試專案，你可以使用測試資源管理器來有效地除錯你的程式碼。

除錯時，我的斷點沒有繫結

你正在除錯的程序不是在 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)）中的專案日誌，並從下拉選單中選擇**專案**。這將顯示與你的專案未完全載入相關的任何錯誤。複製輸出面板中的所有文字，並透過 VS Code 報告問題，確保包含複製的文字。

C# 擴充套件無法啟動伺服器

作為一種解決方法，你可以透過 dotnetAcquisitionExtension.existingDotnetPath 設定，將 .NET 執行時獲取擴充套件指向一個已有的 .NET 7 安裝。

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

我有太多診斷資訊，或者我沒有足夠的診斷資訊

C# 擴充套件允許你配置各種後臺程式碼分析設定。要訪問這些設定，請轉到檔案 > 首選項 > 設定或使用鍵盤快捷鍵（⌘, (Windows、Linux 為 Ctrl+,)）。在搜尋欄中，輸入“analysis”以縮小與程式碼分析相關的設定範圍。在**執行後臺程式碼分析範圍：**下，你可以從下拉選單中選擇分析範圍。預設設定是分析開啟的檔案，但你可以將其自定義為整個解決方案、無或開啟的文件。

Configure Background Code Analysis

你也可以使用 EditorConfig 檔案來配置診斷和程式碼分析。要了解有關 EditorConfig 的更多資訊，請檢視文件。

如果你沒有看到足夠的診斷資訊或根本沒有，可能是因為你的專案沒有完全載入。要檢查是否是這種情況，請參閱我如何讓智慧感知（IntelliSense）正常工作？部分。它提供瞭如何驗證專案是否完全載入的說明。

Razor 編輯器

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

在發現 Blazor 元件之前，C# 開發工具包需要成功載入你的專案。此外，Razor 語言伺服器需要生成一個 project.razor.vscode.bin 檔案才能理解你的專案狀態。如果此檔案未生成，或者生成時沒有任何元件，Razor 體驗可能會受到影響。

為了提高效能，擴充套件有時會推遲生成或載入此檔案，直到你開啟第一個 .razor 或 .cshtml 檔案。為確保你要使用的專案在解決方案資源管理器中沒有錯誤，請仔細檢查它。

如果你的專案已正確載入，請驗證檔案系統中是否存在 project.razor.vscode.bin 檔案，位於 obj\Debug\<tfm> 資料夾中。由於它是一個二進位制檔案，直接驗證檔案內容並不簡單，但總的來說，大多數 Razor 專案應該會生成一個至少 150KB 大小的檔案。如果檔案只有幾千位元組，則意味著標記幫助程式和/或元件可能沒有被正確發現。

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

Razor 檔案中提到了目標框架錯誤

Razor 語言伺服器通常沒有“解決方案”的概念，而是根據專案 obj\Debug\<tfm> 資料夾中是否存在 project.razor.vscode.bin 檔案來載入專案。有時，來自不再使用的目標框架的舊檔案可能會引起混淆，使 Razor 伺服器認為專案是多目標的，或者某些元件仍然被引用而實際上並非如此。

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

IntelliCode

我沒有得到整行補全

當GitHub Copilot擴充套件啟用時，整行補全功能會被停用，以便你利用更高階的AI 補全功能。你可以透過檢查 VS Code 右下角是否存在 Copilot 徽標來驗證 Copilot 是否已啟用。

熱過載

我開始除錯後，熱過載圖示沒有出現

只有在 C# 開發工具包偵錯程式設定中啟用了熱過載選項時，偵錯程式才會啟動熱過載會話。如果該選項已啟用，預計在除錯時熱過載圖示會出現在狀態列中

Hot Reload icon in the bottom bar

你可以點選熱過載圖示，或者透過開啟 **C# Hot Reload** 輸出視窗檢視診斷資訊。如果你兩者都看不到，則該專案可能不受 C# 開發工具包擴充套件的支援，請參閱熱過載支援的專案。

熱過載支援哪些型別的編輯？

有關熱過載支援的 C# 程式碼更改列表，請參閱支援的程式碼更改。

5/3/2024