參與 .NET 檔存放庫

感謝您對參與 .NET 文件感興趣！

本文件涵蓋參與 .NET 文件網站上所裝載文章和程式碼範例的程序。 貢獻可以簡單到像錯字更正，或是複雜到像是新的文章。

.NET 檔網站是從多個存放庫建置的。 這些只是其中一些：

• .NET 概念文章和程式碼片段
• 程式碼範例及程式碼片段
• .NET API 參考
• .NET Compiler Platform SDK 參考
• ML.NET API 參考

參與方針

我們感謝社群對文件的貢獻。 下列清單顯示當您參與 .NET 檔案時要記住的一些指導規則：

• 請勿以大量提取要求來讓我們大吃一驚。 而是請您先提出問題並開始討論，我們會在您投入大量的時間之前，先行確認方向。
• 請勿 在文章中包含內嵌範例程序代碼。
• 請使用 代碼段專案搭配要內嵌在文章中的程序代碼。
• 務必遵循這些指示，以及語態和語調方針。
• 請務必使用範本檔案作為您開始工作的起點。
• 請務必在對文章進行作業之前，先在分叉上建立您自己的分支。
• 務必遵循 GitHub flow(GitHub 流程)。
• 若想要的話，請務必針對參與來撰寫部落格文章和推文 (或透過其他方式)！

遵循這些方針將有助於確保您與我們都有更佳的體驗。

參與程式

步驟 1： 如果您對撰寫新內容或徹底修改現有內容感興趣，請開啟描述 您要執行之動作的問題 。 docs 資料夾內的內容會組織成反映在目錄 （TOC） 中的區段。 請定義主題在 TOC 中的位置。 取得您提案的意見反應。

-或-

選擇現有問題並加以解決。 您可查看 open issues (開啟的問題) 清單，並自願參與任何感興趣的問題：

• 依照 good-first-issue 標籤進行篩選，以取得良好或優先處理的問題。
• 依照 up-for-grabs 標籤進行篩選，以取得適合由社群進行貢獻的問題。 這些問題通常僅需要最少的內容。
• 具備經驗的參與者可處理任何其感興趣的問題。

當找到要處理的問題時，請新增註解來詢問該問題是否處於開啟狀態。

選取要處理的工作之後， 請建立 GitHub 帳戶 並移至步驟 2。

步驟 2： 視需要派 /dotnet/docs 生存放庫（或您要參與的存放庫），併為您的變更建立分支。

如需小型變更，請參閱 瀏覽器中的編輯。

步驟 3：對這個新的分支進行變更。

若此為新主題，您可使用這個範本檔案作為起點。 其包含撰寫指導方針，同時也會說明每篇文章所需的中繼資料，例如作者資訊。 如需 Microsoft Learn 內容中使用的 Markdown 語法詳細資訊，請參閱 Markdown 參考。

流覽至對應至步驟 1 中針對文章決定之 TOC 位置的資料夾。 該資料夾包含該章節中所有文章的 Markdown 檔案。 請視需要建立新的資料夾，以存放您內容的檔案。 該小節的主要文章稱為 index.md。

針對影像及其他靜態資源，請在包含您文章的資料夾內建立一個名為 media 的子資料夾 (如果此子資料夾尚未存在)。 在 [media] 資料夾內，使用文章名稱 (索引檔案除外) 建立一個子資料夾。 如需放置檔案位置的詳細資訊，請參閱 範例資料夾結構 一節。

除非您示範未編譯的建構，否則請勿在文章中內嵌包含程序代碼。 請改用 代碼段 專案，並使用程式碼延伸模組包含程序代碼。 這可確保我們的 CI 系統會驗證您的範例程式代碼。

針對程式碼片段，請在包含您文章的資料夾中建立名為 snippets 的子資料夾 (如果尚未存在)。 在 [snippets] 資料夾內，使用文章名稱建立子資料夾。 在大部分情況下，您會有三種主要 .NET 語言的程式碼片段：C#、F# 與 Visual Basic。 在該情況下，請分別建立名為 chsarp、fsharp 和 vb 的子資料夾，其分別適用於三種專案。 若正在為位於 docs/csharp、docs/fsharp 或 docs/visual-basic 資料夾下的文章建立程式碼片段，由於程式碼片段只會以一種語言呈現，因此可忽略語言子資料夾。 如需放置檔案位置的詳細資訊，請參閱 範例資料夾結構 一節。

程式碼片段為一種小篇幅、重點式的程式碼範例，用以示範文章中提及的概念。 大型程式 (供使用者下載與探索) 應該放在 dotnet/samples 存放庫中。 完整範例涵蓋在參與範例一節中。

步驟 4： 將提取要求 （PR） 從您的分支提交至預設分支。

重要

目前無法在任何 .NET 文件存放庫上使用註解自動化功能。 .NET 文件小組成員將會審查並合併您的 PR。

除非多個問題與相同的PR修正相關，否則每個PR通常會一次處理一個問題。 PR 可以修改一或多個檔案。 如果您要處理不同檔案上的多個修正，建議您使用個別的 PR。

如果您的PR修正了現有的問題，請將 Fixes #Issue_Number 關鍵詞新增至PR描述。 如此一來，在合併 PR 時，就會自動關閉問題。 如需詳細資訊，請參閱 使用 關鍵詞將提取要求連結至問題。

.NET 小組會檢閱您的 PR，並讓您知道是否需要任何其他更新/變更才能核准。

步驟 5：依據與小組的討論，對分支進行任何必要的更新。

維護人員會在套用意見反應並核准變更後，將您的PR合併至預設分支。

我們會定期將所有認可從預設分支推送至即時分支，然後您就能在 .NET 檔中即時看到您的貢獻。 我們一般會在工作週期間每天發佈。

範例資料夾結構

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

注意

假設只有一個語言，語言指南區域中的程式碼片段底下不需要語言資料夾。 例如，在 C# 指南中，假設所有代碼段都是 C#。

如上所示的結構包含一個影像 portability_report.png，以及三個程式碼專案，專案中含有 porting-overview.md 文章中的程式碼片段。

代碼 段/共用資料夾 用於可能跨越相同父資料夾內多個發行項的代碼段，例如 上一個範例中的移植 資料夾。 只有當您有特定理由這樣做時，才使用共用資料夾，例如多個發行項所參考的 XAML 程式代碼，但無法在發行項特定資料夾中編譯。

當這些文章位於相同的父資料夾時，媒體也可以跨文章共用，例如 上一個範例中的移植 資料夾。 如果可能的話，應該避免此 共享資料夾 ，而且只有在合理時才使用。 例如，共用所示範應用程式的一般載入畫面，或共用跨多個文章重複使用的Visual Studio 對話方塊可能很合理。

重要

為了留下歷程記錄，許多包含的程式碼片段會儲存在 dotnet/docs 存放庫中的 /samples 資料夾底下。 如果要大幅變更文章內容，則這些程式碼片段應移至新的結構。 不過，請不要擔心行動代碼段以進行小型變更。

參與範例

我們對程式碼進行了下列區別，以支援我們的內容：

• 範例：讀者可以下載並執行範例。 所有範例都應該是完整的應用程式或程式庫。 在範例建立程式庫的位置，應包含單元測試或可供讀者執行程式碼的應用程式。 這些範例通常會使用多項技術、功能或工具組。 每個範例的 readme.md 檔案會參考一篇文章，您可以閱讀以深入了解每個範例所包含的概念。
• 程式碼片段：說明較小的概念或工作。 它們會進行編譯，但不會成為完整的應用程式。 它們應該會正確執行，但不是典型案例的範例應用程式。 相反地，它們設計成盡可能小到足以說明單一概念或功能。 這些程式碼片段不應該超過一個螢幕的程式碼。

範例儲存在 dotnet/samples 存放庫中。 我們正朝著建立一個讓範例資料夾結構符合文件資料夾結構的模型方向前進。 我們所依循的標準為：

• 最上層資料夾會對應到 docs 存放庫中的最上層資料夾。 例如，docs 存放庫包含一個 machine-learning/tutorials 資料夾，而機器學習教學課程的範例則位於 samples/machine-learning/tutorials 資料夾中。

此外，[core] 和 [standard] 資料夾底下的所有範例都應該在 .NET Core 支援的所有平台上建置並執行。 我們的 CI 建置系統將會強制執行該做法。 最上層 [framework] 資料夾則包含只會在 Windows 上建置並驗證的範例。

請盡可能在適用於指定範例的一組最廣泛平台上建置和執行範例專案。 實際上，這表示盡可能建置以 .NET Core 為基礎的主控台應用程式。 Web 或 UI 架構特定的範例應該視需要新增這些工具。 範例包括 Web 應用程式、行動應用程式、WPF 或 WinForms 應用程式等。

我們將致力於開發適用於所有程式碼的 CI 系統。 當您對範例進行任何更新時，請確定每項更新都是可建置專案的一部分。 在理想情況下，也可針對範例的正確性新增測試。

您所建立的每個完整範例都應該包含 readme.md 檔案。 此檔案應該包含範例的簡短描述 (一或兩個段落)。 您的 readme.md 應該告訴使用者探索此範例將可學習到什麼。 readme.md 檔案應該包含一個 .NET 文件網站上即時文件的連結。 若要決定存放庫中指定檔案與該網站對應的位置，請以 https://learn.microsoft.com/dotnet 取代存放庫路徑中的 /docs。

您的主題也會包含範例的連結。 請直接連結至 GitHub 上範例的資料夾。

撰寫新的範例

範例為可供下載的完整程式與程式庫。 範例的範圍可能很小，但會以可讓使用者自行探索與實驗的方式來示範概念。 範例的指導方針確保讀者可下載與探索。 檢查 Parallel LINQ (PLINQ) 範例，以作為每個指導方針的範例。

1. 範例必須是可建置專案的一部分。 請盡可能在 .NET Core 支援的所有平台上建置專案。 但示範平台特定功能或平台特定工具的範例則除外。

2. 您的範例應符合 運行時間編碼樣式 ，以維持一致性。

   此外，當示範不需要具現化新物件的內容時，我們偏好使用 static 方法，而不是執行個體方法。

3. 您的範例應該包含適當的例外狀況處理。 它應該處理範例內容中可能擲回的所有例外狀況。 例如，呼叫 Console.ReadLine 方法以擷取使用者輸入的範例應該在輸入字串作為引數傳遞至方法時，使用適當的例外狀況處理。 同樣地，如果您的範例預期方法呼叫失敗，則必須處理產生的例外狀況。 請務必處理方法所擲回的特定例外狀況，而不是 Exception 或 SystemException 等基底類別例外狀況。

若要建立範例：

1. 提出問題，或對您目前參與的現有問題新增註解。

2. 撰寫主題，以說明您範例中所示範的概念 (例如：docs/standard/linq/where-clause.md)。

3. 撰寫您的範例 (例如：WhereClause-Sample1.cs)。

4. 建立 Program.cs，其中包含呼叫您範例的主要進入點。 如果已有此檔案，請將呼叫新增至您的範例：

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

您可以使用 .NET CLI 建置任何 .NET 代碼段或範例，而此 CLI 可以隨 .NET SDK 一起安裝。 若要建置並執行您的範例：

1. 移至範例資料夾和組建以檢查是否有錯誤：

   dotnet build
   

2. 執行您的範例：

   dotnet run
   

3. 將 readme.md 新增至您範例的根目錄。

   這應該包含程式碼的簡短描述，並指示使用者前往參考該範例的文章。 readme.md 的最上層，必須具有範例瀏覽器所需的中繼資料。 標頭區塊應包含下欄欄位：

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • languages 集合應包含僅適用於您範例的語言。
   • products 集合應包含僅與您範例相關的產品。

除非有說明，所有範例都會在 .NET 所支援的任何平臺上從命令行建置。 有些 Visual Studio 特定的範例需要 Visual Studio 2017 或更新版本。 此外，有些顯示平台特定功能的範例需要特定平台。 其他範例和程式碼片段需要 .NET Framework 並將在 Windows 平台上執行，而且需要適用於目標 Framework 版本的開發人員套件。

C# 互動式體驗

文章中包含的所有代碼段都會使用 語言標記 來指出來源語言。 C# 中的簡短代碼段可以使用 csharp-interactive 語言標記來指定在瀏覽器中執行的 C# 代碼段。 （內嵌代碼段使用 csharp-interactive 標籤，針對來源中包含的代碼段，請使用 code-csharp-interactive 標記。這些代碼段會顯示文章中的程式 碼窗口 和 輸出視窗 。 一旦使用者執行代碼段，輸出 視窗 會顯示執行互動式程式碼的任何輸出。

C# 互動式體驗會變更我們使用代碼段的方式。 訪客可以執行代碼段來查看結果。 許多因素有助於判斷代碼段或對應的文字是否應該包含輸出的相關信息。

何時顯示預期的輸出，而不執行代碼段

• 文章如果是以初學者為對象，就應該提供輸出，以便讓讀者能夠將其工作輸出與預期的答案做比較。
• 輸出是主題不可或缺的代碼段，應該會顯示該輸出。 例如，格式化文字上的文章應該會顯示文字格式，而不執行代碼段。
• 當代碼段和預期的輸出都很短時，請考慮顯示輸出。 這樣可節省一些時間。
• 文章如果是說明目前文化特性 (Culture) 或不因文化特性而異會如何影響輸出，就應該說明預期的輸出。 互動式 REPL (「讀取、求值、輸出」迴圈) 會在 Linux 型主機上執行。 預設文化特性 (Culture) 和不因文化特性而異會在不同的作業系統與機器上，產生不同的輸出。 文章應該說明 Windows、Linux 及 Mac 系統中的輸出。

何時要從代碼段排除預期的輸出

• 代碼段產生較大輸出的文章不應包含在批注中。 一旦執行代碼段，它就會遮蔽程序代碼。
• 代碼段示範主題的文章，但輸出並不是了解主題不可或缺的一部分。 例如，執行 LINQ 查詢來說明查詢語法後再於輸出集合中顯示每個項目的程式碼。

注意

您可能會注意到某些主題目前未遵循這裡所指定的方針。 我們目前正在努力達到整個網站的一致性。 請查看我們目前正致力於達到特定目標的未解問題清單。

參與非英文內容

目前不接受機器翻譯 (MT) 的內容。 為了改善 MT 內容的品質，我們已轉換成神經 MT 引擎。 我們接受並鼓勵人工翻譯 (HT) 內容的貢獻，這可用於訓練神經 MT 引擎。 經過一段時間，HT 內容的貢獻將可同時改善 HT 與 MT 的品質。 MT 主題將有免責聲明，表示部分主題可能是 MT，而當編輯功能停用時，不會顯示 [編輯] 按鈕。

注意

大部分本地化的檔都無法透過 GitHub 編輯或提供意見反應。 若要提供當地語系化內容的意見反應，請使用 https://aka.ms/provide-feedback 表單。

參與者授權合約

您必須先簽署 .NET Foundation 貢獻授權合約 (CLA)，才能合併您的 PR。 這是針對 .NET Foundation 中專案的單次要求。 您可於 Wikipedia 上閱讀更多關於貢獻授權合約 (CLA) 的資訊。

合約： .NET Foundation 參與者許可協定（CLA）

您不必預先簽署合約。 您可以一如往常地複製、派生和提交 PR。 PR 建立後，CLA Bot 就會為其分類。 如果變更不大 (例如修正錯字)，則 PR 會標記為 cla-not-required。 否則，會歸類為 cla-required。 在您簽署 CLA 之後，目前及未來的所有提取要求都會標示為 cla-signed。