🚀 在 VS Code 中！

C# 開發套件常見問題

使用此常見問題 (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 Multi-platform App UI (MAUI) 應用程式和 Unity 應用程式提供額外支援。這些擴充功能支援現代 .NET 專案格式，也稱為 "sdk-style" 專案。如果您正在建置非 SDK 格式的專案 (例如 .NET Framework 應用程式和 Xamarin 應用程式)，請參閱專案系統章節。

C# 開發套件中包含哪些擴充功能？

今天 C# 開發套件系列中包含的擴充功能有

這些擴充功能的使用受C# 開發套件系列擴充功能 EULA 的規範。

這些擴充功能也有其自身的授權相依性 – 例如，C# 開發套件相依於 C# 擴充功能和 .NET 安裝工具。

為什麼 C# 開發套件沒有啟用 / 找不到 C# 開發套件命令？

當您嘗試編輯 C# 檔案時，C# 開發套件未啟用的原因有幾個。

  1. 未安裝 2.0+ 版本的 C# 擴充功能。C# 開發套件需要 2.0 或更高版本的 C# 擴充功能。請檢查以確保您已安裝 C# 擴充功能，並且您的版本為 2.0 或更高版本。
  2. 工作區偏好 C# 擴充功能。C# 開發套件不支援 .NET Framework 專案，如果您已將 dotnet.preferCSharpExtension 設定設為 true，C# 開發套件將會針對該工作區停用。如果專案不是 .NET Framework 專案，請務必停用此設定。
  3. 使用唯讀作業系統。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# 開發套件]。

Help > Report Issue image

C# 開發套件是開放原始碼嗎？為什麼不是？

否。C# 開發套件是封閉原始碼，但依賴於開放原始碼的 VS Code 用 C# 擴充功能，並且兩者都與開放原始碼元件 (例如 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，而我使用了 Proxy

如果您的系統使用 Proxy 且已停用登錄存取權，您需要在擴充功能設定中明確設定 Proxy URL。當透過環境變數和登錄設定 Proxy 時，會自動偵測 Proxy，但如果您的 Proxy 僅透過登錄機碼管理且登錄存取權已停用，則擴充功能無法找到它。若要設定 Proxy 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# 開發套件功能。

或者，您可以使用設定編輯器中的 [偏好 C# 擴充功能] 工作區設定，將專案和方案載入委派給 C# 擴充功能。請記住，使用此設定時，某些 C# 開發套件功能將無法使用。若要存取此設定，請前往設定編輯器並選取 [工作區] 索引標籤。然後，在搜尋列中搜尋 "Prefer CSharp"，並勾選 [偏好 C# 擴充功能] 設定旁邊的方塊。如果您嘗試載入 .NET Framework 專案，C# 開發套件將會自動顯示通知，詢問您是要將專案更新為 SDK 樣式專案，還是讓 C# 擴充功能載入您的專案或方案，方法是從通知中選取 [使用 C# 擴充功能]。此選項將會自動選取 [偏好 C# 擴充功能] 設定。請注意，您需要重新載入 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 是由套件管理員而不是透過 Microsoft 提供的安裝程式安裝的，就可能發生這種情況。若要修正此問題，請透過套件管理員解除安裝 SDK，然後透過 [下載 .NET] 安裝它。

測試總管

為什麼我的測試沒有顯示在「測試總管」面板中？

確保您的方案包含測試專案。只會包含屬於已開啟方案一部分的測試專案。若要查看測試專案是否為方案的一部分，請在檔案總管中開啟方案總管檢視，並查看專案是否出現在樹狀結構中。以滑鼠右鍵按一下方案節點以新增現有的測試專案，或在方案中建立新的測試專案。

C# 開發套件也要求必須成功建置您的專案，測試才會顯示在「測試總管」面板中。此外，如果對您的專案/方案執行 [清除]，測試 dll 將會從「測試總管」面板中移除。

一旦您驗證您的測試專案是方案的一部分，請在方案總管中以滑鼠右鍵按一下方案，然後選取 [建置] 或使用 ⇧⌘B (Windows, Linux Ctrl+Shift+B) 來建置您的方案。建置完成後，您的測試將會顯示在「測試總管」面板中。

我的測試顯示在「測試總管」面板中，但我無法對其進行偵錯

確保您的測試目標為 NET Core。C# 開發套件不支援 .NET Framework 專案，儘管 .NET Framework 專案可能會載入並顯示為可運作。VS Code 中的偵錯工具不支援 .NET Framework。

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

C# 開發套件要求必須成功建置您的專案，測試才會顯示在「測試總管」面板中。

在方案總管中以滑鼠右鍵按一下方案，然後選取 [建置] 或 ⇧⌘B (Windows, Linux Ctrl+Shift+B) 來建置您的方案。建置完成後，您的測試將會顯示在「測試總管」面板中。

我該如何收集記錄以針對「測試總管」的問題進行疑難排解？

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

  1. 提高「測試總管」詳細程度：瀏覽至 C# 開發套件設定，並將 [測試總管詳細程度] 設定從 minimal 提高到 diagnostic。這將會產生更詳細的記錄。
  2. 檢查「輸出」視窗：在 Visual Studio Code 中開啟 [輸出] 視窗，然後從下拉式清單中選取 [C# 開發套件 - 測試總管]。診斷訊息將會以 [dev] 字首顯示。
  3. 收集下列資訊：回報問題時，請務必包含
    • 來自「輸出」視窗的診斷記錄。
    • 您的作業系統和版本 (例如，Windows 10、macOS 13)。
    • 您正在使用的 C# 開發套件擴充功能版本。前往 [擴充功能] 檢視，然後將滑鼠游標停留在擴充功能上方以檢視版本資訊。

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

偵錯工具

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

確保您已開啟 C# 專案，或使用中的文件是 .cs 或 .razor 檔案。如果除錯工具仍然無法載入，請確保 C# 開發套件和 C# 擴充功能都已啟用。

當我按下 F5 鍵時，它要求我「選取除錯工具」。我該如何知道要選擇哪一個？

如果您嘗試除錯 .NET 主控台應用程式、Blazor Server 應用程式、Blazor WebAssembly 或 Web 應用程式，請務必選取 [C#] 選項。其他選項可能是其他擴充功能的一部分，例如用於 JavaScript 除錯的 [Node] 或用於 Python 除錯的 [Python]，它們不是 C# 開發套件的一部分。

當我按下 F5 鍵時，它會提示我輸入密碼 (僅限 macOS)

macOS 預設停用開發人員模式，如果程式想要用作除錯工具，則會提示輸入密碼以保護使用者。

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

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

為什麼除錯無法運作？

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

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

您正在除錯的程序不是在「偵錯」中建置的，請確保在除錯程序之前先以偵錯方式建置。

C# 編輯器

我該如何讓 IntelliSense 正常運作？

確保您已開啟專案或方案。如果您有多個方案，擴充功能將會自動開啟一個方案，或提示您開啟一個方案。接下來，在 [設定] 搜尋列中搜尋 "Trace"，然後從下拉式清單中將 [Dotnet] > [伺服器:] 設定為 [追蹤]。此選項提供更多輸出資訊，以協助開發人員團隊診斷問題。

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# 擴充功能無法啟動伺服器

作為一種解決方法，您可以將 .NET 執行階段取得擴充功能指向現有的 .NET 7 安裝，並使用 dotnetAcquisitionExtension.existingDotnetPath 設定

{
  "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 檔案為止。若要確保您嘗試使用的專案的方案總管中沒有錯誤，請仔細檢查。

如果您的專案已正確載入，請驗證您的檔案系統上的 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 完成功能。您可以檢查 VS Code 右下角是否顯示 Copilot 標誌，以驗證是否已啟用 Copilot。

熱重新載入

開始偵錯後，未顯示熱重新載入圖示

偵錯工具只有在 C# 開發套件偵錯工具設定中啟用熱重新載入選項時，才會啟動熱重新載入工作階段。如果啟用此選項，則預期在偵錯時，「熱重新載入」圖示會出現在狀態列中

Hot Reload icon in the bottom bar

您可以按一下熱重新載入圖示，或透過開啟 [C# 熱重新載入輸出] 視窗來查看診斷資訊。如果您沒有看到其中任何一個，則專案可能不受 C# 開發套件擴充功能支援，請參閱 熱重新載入支援的專案。

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

如需熱重新載入支援的 C# 程式碼變更清單，請參閱 支援的程式碼變更。

5/3/2024