C# Dev Kit FAQ

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 Multi-platform App UI (MAUI) 應用和 Unity 應用的額外支援。這些擴充套件支援現代 .NET 專案格式，也稱為“SDK 樣式”專案。如果您正在構建非 SDK 格式的專案，例如 .NET Framework 應用和 Xamarin 應用，請參閱專案系統部分。

C# Dev Kit 包含哪些擴充套件？

目前，C# Dev Kit 系列包含以下擴充套件：

這些擴充套件的使用受 C# Dev Kit 系列擴充套件的 EULA 管轄。

這些擴充套件也有自己的許可依賴項——例如，C# Dev Kit 依賴於 C# 擴充套件和 .NET Install Tool。

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

嘗試編輯 C# 檔案時 C# Dev Kit 未啟用有幾個原因。

未安裝 C# 擴充套件的 2.0+ 版本。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 輸出視窗中的資訊。

許可和貢獻

誰可以使用 C# Dev Kit？

C# Dev Kit 可透過社群許可證供符合條件的使用者使用，並且也是現有 Visual Studio 訂閱的一項附加服務。這意味著 C# Dev Kit 已可供擁有有效 Visual Studio 訂閱的開發者使用。

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

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

使用者可以透過 VS Code 的幫助 > 報告問題來報告問題或建議。選擇是 bug、功能請求還是效能問題，然後在一個擴充套件中進行檔案，並從擴充套件列表中選擇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# 擴充套件是 C# Dev Kit 的一部分，完全開源，並受這些許可條款的約束。此擴充套件的原始碼可在 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 演練或 .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"
}

專案系統

解決方案資源管理器報告我的專案不受 C# Dev Kit 支援

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

Project Not Supported in Solution Explorer

要解決此問題，您有兩個選擇。

您可以更新您的專案為 SDK 樣式專案，以訪問所有可用的 C# Dev Kit 功能。

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

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

這通常發生在擴充套件版本不匹配時。C# Dev Kit 要求 C# 擴充套件的版本為 2.0 或更高版本。如果您使用的是 C# 擴充套件的 v1 版本，C# Dev Kit 和 C# Dev Kit 相關命令將無法正常工作。要解決此問題，請將 C# 擴充套件升級到最新版本。

專案系統報告遇到問題

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

Failed to Restore Solution

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

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

選擇顯示錯誤。這會開啟 NuGet 的輸出面板。閱讀錯誤資訊以確定包還原失敗的原因。如果您無法解決問題，請透過 VS Code 報告問題。

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

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

A compatible .NET SDK was not found

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

Output Window Projects Pane

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

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

SDK 也可能未安裝在 C# Dev Kit 已知的目錄中。例如，如果 SDK 是透過包管理器而不是透過 Microsoft 提供的安裝程式安裝的，則可能會發生這種情況。要修復此問題，請透過包管理器解除安裝 SDK，然後透過下載 .NET 進行安裝。

測試資源管理器

為什麼我的測試未顯示在測試資源管理器面板中？

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

C# Dev Kit 還要求在測試顯示在測試資源管理器面板之前已成功構建了您的專案。此外，如果對專案/解決方案執行了清理操作，測試 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 可能無法被檢測到，因為它們偏離了 Microsoft 的官方安裝方法。我們建議遵循官方說明。
構建輸出：確認構建已完成並生成了相應的輸出二進位制檔案，例如 .dll 或 .exe 檔案。
專案載入：確保所有專案都已完成載入。在解決方案資源管理器中，查詢測試專案旁邊的測試圖示以確認它們已被檢測到。

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

確保您的測試目標是 .NET Core。C# Dev Kit 不支援 .NET Framework 專案，儘管 .NET Framework 專案可能會載入並似乎正常工作。VS Code 中的偵錯程式不支援 .NET Framework。

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

C# Dev Kit 要求在測試顯示在測試資源管理器面板之前已成功構建了您的專案。

透過在解決方案資源管理器中右鍵單擊解決方案並選擇構建，或使用 ⇧⌘B（Windows、Linux Ctrl+Shift+B）來構建您的解決方案。構建完成後，您的測試將顯示在測試資源管理器面板中。

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

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

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

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

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

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

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

增加測試資源管理器詳細程度：導航到 C# Dev Kit 設定，並將測試資源管理器詳細程度設定從 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 預設停用開發者模式，並提示輸入密碼以保護使用者，以防程式被用作偵錯程式。

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

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））中檢查專案日誌，並從下拉選單中選擇Projects。這將顯示與您的專案未完全載入相關的任何錯誤。複製輸出面板中的所有文字，並透過 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# Dev Kit 需要成功載入您的專案。此外，Razor 語言伺服器需要生成 project.razor.vscode.bin 檔案才能理解您專案的狀態。如果未生成此檔案，或生成的檔案不包含任何元件，Razor 體驗可能會受到影響。

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

如果您的專案已正確載入，請驗證您的檔案系統上 obj\Debug\<tfm> 資料夾中是否存在 project.razor.vscode.bin 檔案。由於它是一個二進位制檔案，直接驗證檔案內容並不容易，但通常大多數 Razor 專案都會生成一個大小至少為 150KB 的檔案。如果檔案僅有幾 KB，則表示標籤助手和/或元件可能未被正確發現。

要強制重新生成檔案，請關閉所有開啟的 .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 補全功能。您可以透過檢查 Copilot logo 是否出現在 VS Code 右下角來驗證 Copilot 是否已啟用。

熱過載

開始除錯後，熱過載圖示未出現

只有當 C# Dev Kit 偵錯程式設定中的熱過載選項啟用時，偵錯程式才會啟動熱過載會話。如果該選項已啟用，則在除錯期間，狀態列中預期會顯示熱過載圖示。

Hot Reload icon in the bottom bar

您可以單擊熱過載圖示，也可以透過開啟C# Hot Reload 輸出視窗來檢視診斷資訊。如果您兩者都看不到，則專案可能不受 C# Dev Kit 擴充套件支援，請參閱支援熱過載的專案。

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

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

5/3/2024