วิธีการรวมโค้ดในเอกสาร

มีหลายวิธีนอกเหนือจาก ภาพ หน้าจอเพื่อรวมโค้ดในบทความที่เผยแพร่บน Microsoft Learn:

• แต่ละองค์ประกอบ (คำ) ภายในหนึ่งบรรทัด

  นี่คือตัวอย่างของสไตล์ code

  ใช้รูปแบบรหัสเมื่ออ้างถึงพารามิเตอร์และตัวแปรที่มีชื่อในบล็อกโค้ดใกล้เคียงในข้อความของคุณ นอกจากนี้คุณยังสามารถใช้รูปแบบโค้ดสำหรับคุณสมบัติ เมธอด คลาส และคำสำคัญของภาษาได้ สำหรับข้อมูลเพิ่มเติม โปรดดู องค์ประกอบโค้ด ในภายหลังที่บทความนี้

• บล็อกโค้ดในไฟล์ Markdown ของบทความ

      ```csharp
      public static void Log(string message)
      {
          _logger.LogInformation(message);
      }
      ```
  

  ใช้บล็อกโค้ดแบบอินไลน์เมื่อไม่สามารถแสดงโค้ดโดยอ้างอิงกับไฟล์โค้ดได้ สำหรับข้อมูลเพิ่มเติม โปรดดู บล็อกโค้ด ในภายหลังที่บทความนี้

• บล็อกโค้ดโดยอ้างอิงกับไฟล์โค้ดในที่เก็บภายในเครื่อง

  :::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::
  

  สำหรับข้อมูลเพิ่มเติม โปรดดู การอ้างอิงส่วนย่อยของโค้ดในที่เก็บ ในภายหลังที่บทความนี้

• บล็อกโค้ดโดยอ้างอิงกับไฟล์โค้ดในที่เก็บอื่น

  :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::
  

  สำหรับข้อมูลเพิ่มเติม โปรดดู การอ้างอิงส่วนย่อยของโค้ดนอกที่เก็บ ในภายหลังที่บทความนี้

• บล็อกโค้ดที่อนุญาตให้ผู้ใช้รันโค้ดในเบราว์เซอร์

  :::code source="PowerShell.ps1" interactive="cloudshell-powershell":::
  

  สำหรับข้อมูลเพิ่มเติม โปรดดู ส่วนย่อยของโค้ดเชิงโต้ตอบ ในภายหลังที่บทความนี้

นอกเหนือจากการอธิบาย Markdown สำหรับแต่ละวิธีในการรวมโค้ดแล้วบทความนี้ยังมี คำแนะนำทั่วไปสำหรับบล็อกโค้ดทั้งหมด

องค์ประกอบโค้ด

"องค์ประกอบโค้ด" คือคำสำคัญของภาษาการเขียนโปรแกรม ชื่อคลาส ชื่อคุณสมบัติ และอื่นๆ ซึ่งไม่ชัดเจนเสมอไปมีคุณสมบัติเป็นโค้ดอยู่หรือไม่ ตัวอย่างเช่น ชื่อแพคเกจ NuGet ควรได้รับการปฏิบัติเหมือนโค้ด เมื่อมีข้อสงสัย ให้ดูที่ แนวทางการจัดรูปแบบข้อความ

สไตล์โค้ดแบบอินไลน์

เมื่อต้องการรวมองค์ประกอบโค้ดในข้อความบทความ ให้ล้อมรอบด้วยแบ็กทิก (') เพื่อระบุสไตล์โค้ด สไตล์โค้ดแบบอินไลน์ไม่ควรใช้รูปแบบแบ็กทิกสามตัว

Markdown	แสดงผลแล้ว
ตามค่าเริ่มต้น เฟรมเวิร์กของเอนทิตี ตีความคุณสมบัติที่ชื่อ 'Id' หรือ 'ClassnameID' เป็นคีย์หลัก	ตามค่าเริ่มต้น เฟรมเวิร์กของเอนทิตี ตีความคุณสมบัติที่ชื่อ Id หรือ ClassnameID เป็นคีย์หลัก

เมื่อบทความถูกแปลเป็นภาษาท้องถิ่น (แปลเป็นภาษาอื่นๆ ) ข้อความที่มีลักษณะเป็นโค้ดจะไม่ถูกแปล ถ้าคุณต้องการป้องกันไม่ให้มีการแปลเป็นภาษาท้องถิ่นโดยไม่ใช้สไตล์โค้ด โปรดดู สตริงที่ไม่แปลเป็นภาษาท้องถิ่น

สไตล์ตัวหนา

คำแนะนำสไตล์เวอร์ชันเก่าบางรายการระบุตัวหนาสำหรับโค้ดแบบอินไลน์ ตัวหนาเป็นตัวเลือกเมื่อสไตล์โค้ดไม่เป็นไปตามที่ต้องการเพื่อให้สามารถอ่านได้ง่ายขึ้น ตัวอย่างเช่น ตาราง Markdown ที่มีองค์ประกอบโค้ดมากมายอาจดูยุ่งเกินไปกับการจัดรูปแบบโค้ดในทุกที่ หากคุณเลือกที่จะใช้สไตล์ตัวหนา ให้ใช้ ไวยากรณ์สตริงที่ไม่แปลเป็นภาษาท้องถิ่น เพื่อให้แน่ใจว่าไม่มีการแปลโค้ดเป็นภาษาท้องถิ่น

ลิงก์

ลิงก์ไปยังเอกสารอ้างอิงอาจมีประโยชน์มากกว่ารูปแบบโค้ดในบางบริบท ถ้าคุณใช้ลิงก์ อย่าใช้รูปแบบโค้ดกับข้อความลิงก์ การจัดรูปแบบลิงก์เป็นโค้ดอาจบดบังข้อเท็จจริงที่ว่าข้อความนั้นเป็นลิงก์

หากคุณใช้ลิงก์และอ้างถึงองค์ประกอบเดียวกันในบริบทเดียวกันในภายหลัง ให้จัดรูปแบบโค้ดอินสแตนซ์ที่ตามมาแทนลิงก์ ตัวอย่างเช่น:

The first reference to <xref:System.CommandLine> in this text is a link.
Subsequent references to `System.CommandLine` can be in code style.

แสดงผลแล้ว:

การอ้างอิงแรกใน System.CommandLine ข้อความนี้คือลิงก์ การอ้างอิงในภายหลังเพื่อให้ System.CommandLine อยู่ในสไตล์โค้ด

ข้อความตัวอย่าง

ถ้าคุณต้องการให้ผู้ใช้แทนที่ส่วนของโค้ดที่แสดงด้วยค่าของตนเอง ให้ใช้ข้อความตัวอย่างที่ทําเครื่องหมายด้วยวงเล็บมุม ตัวอย่างเช่น:

az group delete -n <ResourceGroupName>

คุณอาจทราบว่าต้องเอาเครื่องหมายวงเล็บออกเมื่อแทนที่ค่าจริง คําแนะนําสไตล์การเขียนของ Microsoft จะเรียกใช้สําหรับตัวเอียง ซึ่งคุณอาจจัดรูปแบบภายในโค้ดอินไลน์แบบวงเล็บมุม:

<ResourceGroupName> คือกลุ่มทรัพยากรที่...

วงเล็บปีกกา { } ไม่ได้รับการสนับสนุนสําหรับการใช้งานเป็นตัวแทนข้อความเชิงไวยากรณ์ อาจสับสนกับเครื่องหมายเดียวกันที่ใช้ในข้อความที่สามารถแทนที่ได้ สตริงรูปแบบ การประมาณค่าในช่วงสตริง เทมเพลตข้อความ และโครงสร้างการเขียนโปรแกรมที่คล้ายกัน

ชื่อตัวยึดสามารถคั่นด้วยเครื่องหมายยัติภังค์ ("เคบับกรณี") ด้วยขีดล่างหรือไม่ได้ถูกคั่นเลย (กรณีปาสคาล) กรณี Kebab อาจสร้างข้อผิดพลาดของไวยากรณ์และขีดล่างอาจขัดแย้งกับการขีดเส้นใต้ ตัวพิมพ์ใหญ่ทั้งหมดอาจขัดแย้งกับค่าคงที่ที่มีชื่อในหลายภาษา แม้ว่าตัวยึดอาจดึงดูดความสนใจไปยังชื่อตัวแทนข้อความด้วย

<Resource-Group-Name> หรือ <ResourceGroupName>

บล็อกโค้ด

ไวยากรณ์สำหรับการรวมโค้ดในเอกสารขึ้นอยู่กับที่ตั้งของโค้ด:

• ในไฟล์ Markdown ของบทความ
• ในไฟล์โค้ดในที่เก็บเดียวกัน
• ในไฟล์โค้ดในที่เก็บแตกต่างกัน

ต่อไปนี้เป็นแนวทางที่ใช้กับบล็อกโค้ดทั้งสามชนิด:

• หน้า จอ
• การตรวจสอบความถูกต้องของโค้ดโดยอัตโนมัติ
• ไฮไลต์บรรทัดสําคัญของโค้ด
• หลีกเลี่ยงแถบเลื่อนแนวนอน
• ระบุรหัสที่ไม่ดีอย่างชัดเจน

ภาพหน้าจอ

วิธีการทั้งหมดที่ระบุไว้ในส่วนก่อนหน้านี้ส่งผลให้บล็อกโค้ดใช้งานได้:

• คุณสามารถคัดลอกและวางจากบล็อกโค้ดเหล่านั้นได้
• ซึ่งจะถูกจัดทำดัชนีโดยเครื่องมือค้นหา
• เข้าถึงได้โดยโปรแกรมอ่านหน้าจอ

นี่เป็นเพียงเหตุผลบางประการที่เราไม่แนะนำให้ใช้ภาพหน้าจอ IDE เป็นวิธีการรวมโค้ดในบทความ ใช้ภาพหน้าจอ IDE สำหรับโค้ดเฉพาะในกรณีที่คุณกำลังแสดงบางอย่างเกี่ยวกับ IDE เอง อย่างเช่น IntelliSense อย่าใช้ภาพหน้าจอเพื่อแสดงการใส่สีและการไฮไลต์

การตรวจสอบความถูกต้องของโค้ด

ที่เก็บบางรายการมีการใช้กระบวนการที่คอมไพล์โค้ดตัวอย่างทั้งหมดโดยอัตโนมัติเพื่อตรวจสอบข้อผิดพลาด ที่เก็บ .NET ทำสิ่งนี้ สำหรับข้อมูลเพิ่มเติม โปรดดู การมีส่วนร่วม ในที่เก็บ .NET

ถ้าคุณกำลังรวมบล็อกโค้ดจากที่เก็บอื่น ให้ทำงานกับเจ้าของในกลยุทธ์การบำรุงรักษาสำหรับโค้ดเพื่อให้โค้ดที่มีอยู่ของคุณไม่เสียหายหรือล้าสมัยเนื่องจากมีการจัดส่งไลบรารีเวอร์ชันใหม่ที่มีการใช้โค้ด

การเน้น

โดยทั่วไปส่วนย่อยจะมีโค้ดมากกว่าที่จำเป็นเพื่อให้บริบท ซึ่งจะช่วยให้อ่านได้ง่ายขึ้นเมื่อคุณไฮไลต์บรรทัดสำคัญที่คุณกำลังโฟกัสในส่วนย่อย ดังเช่นในตัวอย่างนี้:

คุณไม่สามารถไฮไลต์โค้ดเมื่อคุณรวมโค้ดในไฟล์ Markdown ของบทความ ซึ่งทำงานได้เฉพาะสำหรับส่วนย่อยของโค้ดที่รวมอยู่ด้วยการอ้างอิงไปยังไฟล์โค้ด

แถบเลื่อนแนวนอน

บ่งบรรทัดที่ยาวเพื่อหลีกเลี่ยงการใช้แถบเลื่อนแนวนอน แถบเลื่อนบนบล็อกโค้ดทำให้อ่านโค้ดยาก แถบเลื่อนดังกล่าวจะเป็นปัญหาโดยเฉพาะอย่างยิ่งบนบล็อกโค้ดที่ยาวกว่า ซึ่งอาจเป็นไปไม่ได้ที่จะเห็นแถบเลื่อนและบรรทัดที่คุณต้องการอ่านในเวลาเดียวกัน

แนวทางปฏิบัติที่ดีสำหรับการลดแถบเลื่อนแนวนอนบนบล็อกโค้ดให้เหลือสั้นที่สุดคือ การแบ่งบรรทัดโค้ดที่มีความยาวมากกว่า 85 อักขระ แต่โปรดจำไว้ว่าการมีหรือไม่มีแถบเลื่อน ไม่ได้เป็นเกณฑ์ของความสามารถในการอ่านอย่างเดียวเท่านั้น ถ้าแบ่งบรรทัดก่อน 85 จะส่งผลให้ความสามารถในการอ่านหรือความสะดวกในการคัดลอกและวางแย่ลง โปรดดำเนินการหลังจากบรรทัดที่ 85

ระบุรหัสที่ไม่ดีอย่างชัดเจน

ในบางสถานการณ์ การชี้รูปแบบการเข้ารหัสที่ควรหลีกเลี่ยงนั้นจะเป็นประโยชน์ เช่น:

• โค้ดที่จะทําให้เกิดข้อผิดพลาดของคอมไพเลอร์หากพยายาม
• โค้ดที่จะคอมไพล์อย่างถูกต้อง แต่ไม่แนะนํา

สําหรับสถานการณ์เหล่านี้:

• อธิบายข้อผิดพลาดทั้งในข้อคิดเห็นโค้ดและข้อความบทความ

  ผู้อ่านมักจะข้ามข้อความบทความและดูเฉพาะที่โค้ดดังนั้นจึงไม่เพียงพอที่จะอธิบายข้อผิดพลาดในข้อความบทความเท่านั้น นอกจากนี้ยังไม่เพียงพอที่จะอธิบายข้อผิดพลาดเฉพาะในความคิดเห็นของโค้ดเท่านั้นเนื่องจากความคิดเห็นรหัสไม่ได้แปลเป็นภาษาท้องถิ่น

• พิจารณาการแสดงข้อคิดเห็นเกี่ยวกับโค้ดหากจะทําให้เกิดข้อผิดพลาดของคอมไพเลอร์

  รหัสที่ถูกแสดงข้อคิดเห็นจะไม่รบกวนระบบการผสานรวมแบบต่อเนื่อง (CI) หาก repo ของบทความมีหนึ่งรายการในขณะนี้หรือนํามาใช้ในอนาคต

สําหรับตัวอย่างของวิธีการแสดงโค้ดที่ไม่แนะนํา โปรดดู ตัวอย่างการใช้งาน Rune: การเปลี่ยนตัวพิมพ์ตัวอักษร ในตัวอย่างนี้ คําแนะนําเพื่อหลีกเลี่ยงจะถูกสร้างขึ้นในโค้ดเอง ตามชื่อเมธอด C# คือConvertToUpperBadExample

บล็อกโค้ดแบบอินไลน์

ใช้บล็อกโค้ดแบบอินไลน์เฉพาะเมื่อไม่สามารถแสดงโค้ดโดยอ้างอิงกับไฟล์โค้ดได้ โดยทั่วไปโค้ดแบบอินไลน์นั้นยากต่อการทดสอบและการอัปเดตให้เป็นเวอร์ชันล่าสุดเมื่อเทียบกับไฟล์โค้ดที่เป็นส่วนหนึ่งของโครงการที่สมบูรณ์ และโค้ดแบบอินไลน์อาจไม่ใช้บริบทที่อาจช่วยให้นักพัฒนาเข้าใจและใช้โค้ดได้ ข้อควรพิจารณาเหล่านี้ใช้กับภาษาการเขียนโปรแกรมเป็นหลัก นอกจากนี้ยังสามารถใช้บล็อกโค้ดแบบอินไลน์สำหรับเอาต์พุตและอินพุต (เช่น JSON) ภาษาคิวรี (เช่น SQL) และภาษาการเขียนสคริปต์ (เช่น PowerShell) ได้อีกด้วย

มีสองวิธีในการระบุส่วนของข้อความในไฟล์บทความคือบล็อกโค้ด: โดยการ เฟนทิ กในแบ็กทิกสามตัว ('') หรือโดยการเยื้อง การล้อมรอบโค้ดด้วยอักขระเป็นที่นิยมเพราะมันช่วยให้คุณระบุภาษาได้ หลีกเลี่ยงการใช้การเยื้องเนื่องจากมันทำให้ผิดพลาดได้อย่างง่ายดาย และอาจเป็นเรื่องยากสำหรับนักเขียนคนอื่นที่จะเข้าใจเจตนาของคุณเมื่อต้องการแก้ไขบทความของคุณ

ตัวบ่งชี้ภาษาจะถูกวางไว้ทันทีหลังจากเปิดแบ็กทิกสามตัว ดังในตัวอย่างต่อไปนี้:

Markdown:

    ```json
    {
        "aggregator": {
            "batchSize": 1000,
            "flushTimeout": "00:00:30"
        }
    }
    ```

แสดงผลแล้ว:

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

เคล็ดลับ

GitHub Flavored Markdown สนับสนุนบล็อกโค้ดคั่นด้วยตัวหลอม (~) เช่นเดียวกับแบ็กทิก (') สัญลักษณ์ที่ใช้ในการเปิดและปิดบล็อกรหัสต้องสอดคล้องกันภายในบล็อกรหัสเดียวกัน

สำหรับข้อมูลเกี่ยวกับค่าที่คุณสามารถใช้เป็นตัวบ่งชี้ภาษา โปรดดู ชื่อภาษาและนามแฝง

ถ้าคุณใช้คําภาษาหรือสภาพแวดล้อมหลังจากแบ็กทิกสามตัว ('') ที่ไม่ได้รับการรองรับ คํานั้นจะปรากฏในแถบชื่อส่วนของโค้ดบนหน้าที่แสดง เมื่อใดก็ตามที่เป็นไปได้ ให้ใช้ตัวบ่งชี้ภาษาหรือสภาพแวดล้อมในบล็อกโค้ดแบบอินไลน์ของคุณ

หมายเหตุ

ถ้าคุณคัดลอกและวางโค้ดจากเอกสาร Word ตรวจสอบให้แน่ใจว่าไม่มี "curly quotes," ซึ่งไม่ถูกต้องในโค้ด ถ้ามี ให้เปลี่ยนกลับเป็นเครื่องหมายคำพูดปกติ (' และ ") อีกวิธีหนึ่งคือพึ่งพา Learn Authoring Pack คุณลักษณะการแทนที่ smart quote

การอ้างอิงส่วนย่อยของโค้ดในที่เก็บ

แนวทางที่นิยมในการรวมส่วนย่อยของโค้ดสำหรับภาษาการเขียนโปรแกรมใน Docs คือการอ้างอิงไปยังไฟล์โค้ด วิธีนี้ช่วยให้คุณสามารถไฮไลต์บรรทัดของโค้ดและทำให้บริบทของส่วนย่อยที่กว้างขึ้น ซึ่งมีอยู่บน GitHub สำหรับนักพัฒนาที่จะใช้ คุณสามารถรวมโค้ดโดยใช้รูปแบบเครื่องหมายทวิภาค (:::)ด้วยตนเอง หรือใน Visual Studio Code ด้วยความช่วยเหลือของ Learn Authoring Pack

1. ใน Visual Studio Code ให้คลิก Alt + M หรือ Option + M และเลือก Snippet
2. เมื่อเลือก Snippet แล้ว คุณจะได้รับพร้อมท์สำหรับการค้นหาแบบสมบูรณ์ การค้นหาแบบกำหนดขอบเขต หรือการอ้างอิงข้ามที่เก็บข้อมูล เมื่อต้องการค้นหาภายในเครื่อง ให้เลือกการค้นหาแบบสมบูรณ์
3. ป้อนคำค้นหาเพื่อค้นหาไฟล์ เมื่อคุณพบไฟล์แล้ว ให้เลือกไฟล์
4. ถัดไป ให้เลือกตัวเลือกเพื่อกำหนดว่าต้องรวมบรรทัดใดของโค้ดในส่วนย่อย ตัวเลือกคือ: ID, ช่วง และ ไม่มี
5. โดยขึ้นอยู่กับการเลือกของคุณจากขั้นตอนที่ 4 ให้ป้อนค่าหากจำเป็น

แสดงไฟล์โค้ดทั้งหมด:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

แสดงส่วนของไฟล์โค้ดโดยการระบุหมายเลขบรรทัด:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

แสดงส่วนของไฟล์โค้ดโดยการระบุชื่อส่วนย่อย:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

ส่วนต่อไปนี้อธิบายตัวอย่างเหล่านี้:

• ใช้พาธสัมพัทธ์กับไฟล์โค้ด
• รวมเฉพาะหมายเลขบรรทัดที่เลือก
• อ้างอิงส่วนย่อยที่มีชื่อ
• ไฮไลต์บรรทัดที่เลือก

สำหรับข้อมูลเพิ่มเติม โปรดดู การอ้างอิงไวยากรณ์ส่วนย่อย ในภายหลังที่บทความนี้

พาธไปยังไฟล์โค้ด

ตัวอย่าง:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

ตัวอย่างนี้มาจากที่เก็บเอกสาร ASP.NET ไฟล์ของบทความaspnetcore/data/ef-mvc/crud.md ไฟล์โค้ดจะอ้างอิงโดยพาธเชิงสัมพัทธ์ไปยังaspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs ในที่เก็บข้อมูลเดียวกัน

หมายเลขบรรทัดที่เลือก

ตัวอย่าง:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

ตัวอย่างนี้แสดงเฉพาะบรรทัด 2-24 และ 26 ของไฟล์โค้ด StudentController.cs

ต้องการส่วนย่อยที่มีชื่อมากกว่าหมายเลขบรรทัดที่เขียนโค้ดแบบตรงไปตรงมาตามที่อธิบายไว้ในหัวข้อถัดไป

ส่วนย่อยที่มีชื่อ

ตัวอย่าง:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

ใช้เฉพาะตัวอักษรและขีดล่างสำหรับชื่อ

ตัวอย่างจะแสดงส่วน snippet_Create ของไฟล์โค้ด ไฟล์รหัสสำหรับตัวอย่างนี้มีแท็กส่วนย่อยในความคิดเห็นในโค้ด C#:

// code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

ส่วนย่อยของโค้ดที่มีชื่อสามารถซ้อนกันได้ ดังที่แสดงในตัวอย่างต่อไปนี้:

// <Method>
public static void SomeMethod()
{
    // <Line>
    // Single line of code.
    // </Line>
}
// </Method>

เมื่อมีการ Method แสดงส่วนย่อยของ Line โค้ด แท็กจะไม่รวมอยู่ในผลลัพธ์ที่แสดงผล

เมื่อใดก็ตามที่คุณสามารถทำได้ ให้อ้างอิงไปยังส่วนที่มีชื่อแทนที่จะระบุหมายเลขบรรทัด การอ้างอิงหมายเลขบรรทัดเปราะบางเนื่องจากไฟล์โค้ดมีการเปลี่ยนแปลงในรูปแบบที่ทำให้เกิดการเปลี่ยนแปลงหมายเลขบรรทัดอย่างหลีกเลี่ยงไม่ได้ คุณไม่จำเป็นต้องได้รับแจ้งเกี่ยวกับการเปลี่ยนแปลงดังกล่าว ในที่สุดบทความของคุณจะเริ่มแสดงบรรทัดที่ไม่ถูกต้องและคุณไม่มีเบาะแสอะไรเกี่ยวกับการเปลี่ยนแปลง

การเน้นบรรทัดที่เลือก

ตัวอย่าง:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5":::

ตัวอย่างจะเน้นบรรทัด 2 และ 5 นับจากจุดเริ่มต้นของส่วนย่อยที่แสดง หมายเลขบรรทัดที่ทำการไฮไลต์จะไม่นับจากจุดเริ่มต้นของไฟล์โค้ด กล่าวอีกนัยหนึ่งคือ บรรทัดที่ 3 และ 6 ของไฟล์โค้ดจะถูกเน้น

การอ้างอิงส่วนย่อยของโค้ดนอกที่เก็บ

หากไฟล์โค้ดที่คุณต้องการอ้างอิงอยู่ในที่เก็บอื่น ให้ตั้งค่าที่เก็บโค้ดเป็น ที่เก็บข้อมูลแบบขึ้นต่อกัน เมื่อคุณทำเช่นนั้น คุณต้องระบุชื่อ ชื่อนั้นจะทำงานเหมือนกับชื่อโฟลเดอร์เพื่อวัตถุประสงค์ในการอ้างอิงโค้ด

ตัวอย่างเช่นที่เก็บ docs คือ Azure/azure-docs และที่เก็บโค้ดคือ Azure/azure-functions-durable-extension

ในโฟลเดอร์รูทของ azure-docs ให้เพิ่มส่วนต่อไปนี้ใน .openpublishing.publish.config.json:

    {
      "path_to_root": "samples-durable-functions",
      "url": "https://github.com/Azure/azure-functions-durable-extension",
      "branch": "main",
      "branch_mapping": {}
    },

ตอนนี้เมื่อคุณอ้างถึง samples-durable-functions ราวกับว่าเป็นโฟลเดอร์ใน azure-docs คุณกำลังอ้างถึงโฟลเดอร์รูทในที่เก็บ azure-functions-durable-extension

คุณสามารถรวมโค้ดโดยใช้รูปแบบเครื่องหมายทวิภาค (:::)ด้วยตนเอง หรือใน Visual Studio Code ด้วยความช่วยเหลือของ Learn Authoring Pack

1. ใน Visual Studio Code ให้คลิก Alt + M หรือ Option + M และเลือก Snippet
2. เมื่อเลือก Snippet แล้ว คุณจะได้รับพร้อมท์สำหรับการค้นหาแบบสมบูรณ์ การค้นหาแบบกำหนดขอบเขต หรือการอ้างอิงข้ามที่เก็บข้อมูล หากต้องการค้นหาในที่เก็บข้อมูลทั้งหมด ให้เลือกการอ้างอิงข้ามที่เก็บข้อมูล
3. คุณจะได้รับการเลือกของที่เก็บข้อมูลที่อยู่ใน .openpublishing.publish.config.json เลือกที่เก็บข้อมูล
4. ป้อนคำค้นหาเพื่อค้นหาไฟล์ เมื่อคุณพบไฟล์แล้ว ให้เลือกไฟล์
5. ถัดไป ให้เลือกตัวเลือกเพื่อกำหนดว่าต้องรวมบรรทัดใดของโค้ดในส่วนย่อย ตัวเลือกคือ: ID, ช่วง และ ไม่มี
6. โดยขึ้นอยู่กับการเลือกของคุณจากขั้นตอนที่ 5 ให้ป้อนค่า

การอ้างอิงส่วนย่อยของคุณจะมีลักษณะดังนี้:

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5":::

ในที่เก็บ azure-functions-durable-extension ไฟล์โค้ดนั้นอยู่ในโฟลเดอร์ samples/csx/shared ตามที่ระบุไว้ ก่อนหน้านี้ หมายเลขบรรทัดสำหรับการไฮไลต์จะสัมพันธ์กับจุดเริ่มต้นของส่วนย่อยมากกว่าจุดเริ่มต้นของไฟล์

หมายเหตุ

ชื่อที่คุณกําหนดให้กับที่เก็บข้อมูลแบบขึ้นต่อกันนั้นสัมพันธ์กับรากของที่เก็บหลัก แต่ tilde (~) หมายถึงรูทของ docset รูท docset จะถูกกําหนดโดย build_source_folder ใน.openpublishing.publish.config.json พาธไปยังส่วนย่อยของโค้ดในตัวอย่างก่อนหน้านี้ทำงานในที่เก็บ Docs ของ azure เนื่องจาก build_source_folderอ้างถึงรูทที่เก็บ (.) หาก build_source_folder เป็น articles พาธจะเริ่มต้นด้วย ~/../samples-durable-functions แทนที่จะเป็น ~/samples-durable-functions

ส่วนย่อยในสมุดบันทึก Jupyter

คุณสามารถอ้างอิงเซลล์ในสมุดบันทึก Jupyter เป็นส่วนย่อยของโค้ดได้ เพื่ออ้างอิงเซลล์:

1. เพิ่มเมตาดาต้าของเซลล์ลงในสมุดบันทึกสําหรับเซลล์ที่คุณต้องการอ้างอิง
2. ตั้งค่าการเข้าถึงที่เก็บ
3. ใช้ไวยากรณ์ส่วนย่อยของสมุดบันทึก Jupyter ในไฟล์ markdown ของคุณ

เพิ่มเมตาดาต้าลงในสมุดบันทึก

1. ตั้งชื่อเซลล์โดยการเพิ่มเมตาดาต้าของเซลล์ในสมุดบันทึก Jupyter

   • ใน Jupyter คุณสามารถแก้ไขเมตาดาต้าของเซลล์ได้โดยการเปิดใช้งานแถบเครื่องมือเซลล์ก่อน: ดู>แถบเครื่องมือ>เซลล์ แก้ไขเมตาดาต้า
   • เมื่อเปิดใช้งานแถบเครื่องมือเซลล์แล้ว ให้เลือก แก้ไขเมตาดาต้า บนเซลล์ที่คุณต้องการตั้งชื่อ
   • หรือคุณสามารถแก้ไขเมตาดาต้าได้โดยตรงในโครงสร้าง JSON ของสมุดบันทึก

2. ในเมตาดาต้าของเซลล์ ให้เพิ่มแอตทริบิวต์ "ชื่อ":

   "metadata": {"name": "<name>"},
   

   ตัวอย่างเช่น:

   "metadata": {"name": "workspace"},
   

   เคล็ดลับ

   คุณสามารถเพิ่มเมตาดาต้าอื่น ๆ ที่คุณต้องการช่วยคุณติดตามตําแหน่งที่มีการใช้เซลล์ ตัวอย่างเช่น:

       "metadata": {
         "name": "workspace",
         "msdoc": "how-to-track-experiments.md"
       },
   

ตั้งค่าการเข้าถึงที่เก็บ

ถ้าไฟล์สมุดบันทึกที่คุณต้องการอ้างอิงอยู่ในที่เก็บอื่น ให้ตั้งค่าที่เก็บโค้ดเป็นที่เก็บข้อมูลแบบขึ้นต่อกัน

การอ้างอิงไวยากรณ์ส่วนย่อยของสมุดบันทึก Jupyter

เมื่อสมุดบันทึกของคุณมีเมตาดาต้าที่จําเป็นแล้ว ให้อ้างอิงในไฟล์ markdown ของคุณ <cell-name-value>ใช้คุณเพิ่มลงในสมุดบันทึก และ<path>คุณตั้งค่าเป็นที่เก็บแบบขึ้นต่อกันของคุณ

[!notebook-<language>[] (<path>/<notebook-name.ipynb>?name=<cell-name-value>)]

ตัวอย่างเช่น:

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

สำคัญ

ไวยากรณ์นี้เป็นส่วน Markdown ของบล็อก ต้องใช้บนบรรทัดของตนเอง

ใช้ภาษาที่รองรับสําหรับตัว<language>ระบุ

ส่วนย่อยของโค้ดแบบโต้ตอบ

บล็อกโค้ดเชิงโต้ตอบแบบอินไลน์

สำหรับภาษาต่อไปนี้ ส่วนย่อยของโค้ดสามารถเรียกใช้งานได้ในหน้าต่างเบราว์เซอร์:

• Azure Cloud Shell
• Azure PowerShell Cloud Shell
• C# REPL

เมื่อเปิดใช้งานโหมดการโต้ตอบ กล่องโค้ดที่แสดงผลจะมีปุ่ม ลอง หรือ รัน ตัวอย่างเช่น:

    ```azurepowershell-interactive
    New-AzResourceGroup -Name myResourceGroup -Location westeurope
    ```

จะแสดงดังต่อไปนี้:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

And

    ```csharp-interactive
    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");
    ```

แสดงผลเป็น:

    var aFriend = "Maria";
    Console.WriteLine($"Hello {aFriend}");

เมื่อต้องการเปิดใช้งานคุณลักษณะนี้สำหรับบล็อกโค้ดเฉพาะเจาะจง ให้ใช้ตัวระบุภาษาพิเศษ ตัวเลือกที่ใช้ได้คือ:

• azurepowershell-interactive - เปิดใช้งาน Azure PowerShell Cloud Shell ดังในตัวอย่างก่อนหน้า
• azurecli-interactive - เปิดใช้งาน Azure Cloud Shell
• csharp-interactive - เปิดใช้งาน C# REPL

สำหรับ Azure Cloud Shell และ PowerShell Cloud Shell ผู้ใช้สามารถเรียกใช้คำสั่งกับบัญชี Azure ของตนเองเท่านั้น

ส่วนย่อยของโค้ดที่รวมอยู่ในการอ้างอิง

คุณสามารถเปิดใช้งานโหมดโต้ตอบสำหรับส่วนย่อยของโค้ดที่รวมไว้โดยการอ้างอิง เมื่อต้องการเปิดใช้งานคุณลักษณะนี้สำหรับโค้ดบล็อกเฉพาะเจาะจง ให้เลือกแอตทริบิวต์ interactive ค่าแอตทริบิวต์ที่พร้อมใช้งานคือ:

• cloudshell-powershell - เปิดใช้งาน Azure PowerShell Cloud Shell ดังในตัวอย่างก่อนหน้า
• cloudshell-bash - เปิดใช้งาน Azure Cloud Shell
• try-dotnet - เปิดใช้งาน Try .NET
• try-dotnet-class - เปิดใช้งาน Try .NET ที่มีการยกระดับของคลาส
• try-dotnet-method - เปิดใช้งาน Try .NET ที่มีการยกระดับของเมธอด

ยกตัวอย่างเช่น

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

สำหรับ Azure Cloud Shell และ PowerShell Cloud Shell ผู้ใช้สามารถเรียกใช้คำสั่งกับบัญชี Azure ของตนเองเท่านั้น

สำหรับประสบการณ์การใช้งาน .NET Interactive เนื้อหาของบล็อกโค้ดของคุณจะขึ้นอยู่กับประสบการณ์การใช้งานการยกระดับสามแบบที่คุณเลือก:

• ไม่มีการยกระดับ (try-dotnet): บล็อกโค้ดควรแสดงข้อความโปรแกรมแบบเต็ม ตัวอย่างเช่นไฟล์ Program.cs ที่สร้างโดย dotnet new console จะถูกต้อง สิ่งเหล่านี้มีประโยชน์มากที่สุดในการแสดงโปรแกรมขนาดเล็กทั้งหมดรวมถึง using คำสั่งที่จำเป็น ไม่รองรับข้อความระดับบนสุดในขณะนี้
• การ ยกระดับวิธีการ (try-dotnet-method): บล็อกโค้ดควรแสดงเนื้อหาของ Main วิธีการ ในแอปพลิเคชันคอนโซล คุณสามารถสมมติ using คำสั่งที่เพิ่มโดยเทมเพลต dotnet new console ได้ การตั้งค่านี้มีประโยชน์มากที่สุดสำหรับตัวอย่างข้อมูลสั้นๆ ที่แสดงฟีเจอร์หนึ่ง
• การ ยกระดับคลาส (try-dotnet-class): บล็อกโค้ดควรแสดงถึงคลาสที่มี Main วิธีการ เป็นจุดเริ่มต้นของโปรแกรม สิ่งเหล่านี้สามารถใช้เพื่อแสดงว่าสมาชิกของชั้นเรียนโต้ตอบอย่างไรได้

การอ้างอิงไวยากรณ์ของส่วนย่อย

ไวยากรณ์:

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

สำคัญ

ไวยากรณ์นี้เป็นส่วน Markdown ของบล็อก ต้องใช้บนบรรทัดของตนเอง

• <language> (ทางเลือก)

  • ภาษาของส่วนย่อยของโค้ด สำหรับข้อมูลเพิ่มเติม โปรดดูหัวข้อ ภาษาที่รองรับ ภายหลังในบทความนี้

• <path> (บังคับ)

  • เส้นทางสัมพัทธ์ในระบบไฟล์ที่ระบุไฟล์ส่วนย่อยของโค้ดเพื่ออ้างอิง

• <attribute> และ <attribute-value> (ไม่บังคับ)

  • ใช้ร่วมกันเพื่อระบุวิธีการดึงโค้ดจากไฟล์และวิธีการที่จะแสดง:
    • range: 1,3-5 ช่วงของบรรทัด ตัวอย่างนี้ประกอบด้วยบรรทัด 1, 3, 4, และ 5
    • id: Create ID ของส่วนย่อยที่จําเป็นต้องแทรกจากไฟล์โค้ด ค่านี้ไม่สามารถอยู่ร่วมกับช่วงได้
    • highlight: 2-4,6 ช่วงและ/หรือหมายเลขบรรทัดที่จําเป็นต้องเน้นในส่วนย่อยของโค้ดที่สร้างขึ้น การกำหนดหมายเลขสัมพันธ์กับบรรทัดที่แสดง (ตามที่ระบุโดยช่วงหรือ id) ไม่ใช่ไฟล์
    • interactive: ค่าสตริง cloudshell-powershell, cloudshell-bash, try-dotnet, try-dotnet-class, try-dotnet-method กำหนดชนิดของการโต้ตอบที่เปิดใช้งาน
    • สำหรับรายละเอียดเกี่ยวกับการแทนชื่อแท็กในไฟล์ต้นฉบับส่วนย่อยของโค้ดตามภาษา โปรดดูคำแนะนำ DocFX

ภาษาที่รองรับ

ชุดการเขียนแก้ Learn มีคุณลักษณะเพื่อให้การดําเนินการคําสั่งเสร็จสมบูรณ์และการตรวจสอบความถูกต้องของตัวระบุภาษาที่พร้อมใช้งานสําหรับบล็อกโค้ดแบบรั้ว

บล็อกโค้ดแบบล้อมด้วยอักขระ

ชื่อ	นามแฝงที่ถูกต้อง
.NET Core CLI	dotnetcli
1C	1c
ABNF	abnf
บันทึกการเข้าถึง	accesslog
Ada	ada
ARM assembler	armasm, arm
AVR assembler	avrasm
ActionScript	actionscript, as
Alan	alan, i
AngelScript	angelscript, asc
ANTLR	antlr
Apache	apache, apacheconf
AppleScript	applescript, osascript
Arcade	arcade
AsciiDoc	asciidoc, adoc
AspectJ	aspectj
ASPX	aspx
ASP.NET (C#)	aspx-csharp
ASP.NET (VB)	aspx-vb
AutoHotkey	autohotkey
AutoIt	autoit
Awk	awk, , mawk, nawkgawk
Axapta	axapta
AzCopy	azcopy
Azure CLI	azurecli
Azure CLI (เชิงโต้ตอบ)	azurecli-interactive
Azure Powershell	azurepowershell
Azure Powershell (เชิงโต้ตอบ)	azurepowershell-interactive
การวิจารณ์	bash, , shzsh
พื้นฐาน	basic
BNF	bnf
C	c
C#	csharp, cs
C# (เชิงโต้ตอบ)	csharp-interactive
C++	cpp, c, cc, h, c++, , h++hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Cache Object Script	cos, cls
CMake	cmake, cmake.in
Coq	coq
CSP	csp
CSS	css
Cap'n Proto	capnproto, capnp
Clojure	clojure, clj
CoffeeScript	coffeescript, , coffee, csoniced
Crmsh	crmsh, , crmpcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
ไฟล์ DNS Zone	dns, , zonebind
DOS	dos, , batcmd
Dart	dart
Delphi	delphi, dpr, dfm, pas, pascal, freepascal, , lazarus, lprlfm
Diff	diff, patch
Django	django, jinja
ไฟล์ตัวเทียบ	dockerfile, docker
dsconfig	dsconfig
DTS (Device Tree)	dts
Dust	dust, dst
Dylan	dylan
EBNF	ebnf
Elixir	elixir
Elm	elm
Erlang	erlang, erl
Excel	excel, , xlsxlsx
Extempore	extempore, , xtlangxtm
F#	fsharp, fs
FIX	fix
Fortran	fortran, , f90f95
G-Code	gcode, nc
Gams	gams, gms
GAUSS	gauss, gss
GDScript	godot, gdscript
Gherkin	gherkin
GN for Ninja	gn, gni
ไป	go, golang
Golo	golo, gololang
Gradle	gradle
GraphQL	graphql
Groovy	groovy
HTML	html, xhtml
HTTP	http, https
Haml	haml
แฮนด์	handlebars, , hbs, html.hbshtml.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
Hy	hy, hylang
Ini	ini
Inform7	inform7, i7
IRPF90	irpf90
JSON	json
Java	java, jsp
JavaScript	javascript, , jsjsx
Kotlin	kotlin, kt
Kusto	kusto
Leaf	leaf
Lasso	lasso, , lslassoscript
น้อยกว่า	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, , mkmak
Markdown	markdown, , md, mkdownmkd
Mathematica	mathematica, , mmawl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
mIRC Scripting Language	mirc, mrc
Mizar	mizar
Managed Object Format	mof
Mojolicious	mojolicious
Monkey	monkey
Moonscript	moonscript, moon
MS Graph (เชิงโต้ตอบ)	msgraph-interactive
N1QL	n1ql
NSIS	nsis
Nginx	nginx, nginxconf
Nimrod	nimrod, nim
Nix	nix
OCaml	ocaml, ml
Objective C	objectivec, , mm, objcobj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Oracle Rules Language	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	php, php3, php4, php5php6
Parser3	parser3
Perl	perl, , plpm
ข้อความธรรมดาที่ไม่มีการไฮไลต์	plaintext
Pony	pony
PostgreSQL & PL/pgSQL	pgsql, , postgrespostgresql
พาวเวอร์เชลล์	powershell, ps
PowerShell (เชิงโต้ตอบ)	powershell-interactive
กำลังประมวลผล	processing
Prolog	prolog
คุณสมบัติ	properties
Protocol Buffers	protobuf
Puppet	puppet, pp
Python	python, , pygyp
ผลลัพธ์ของ Python profiler	profile
Q#	qsharp
Q	k, kdb
QML	qml
R	r
Razor CSHTML	cshtml, , razorrazor-cshtml
ReasonML	reasonml, re
RenderMan RIB	rib
RenderMan RSL	rsl
Roboconf	graph, instances
Robot Framework	robot, rf
ไฟล์ข้อมูลจำเพาะของ RPM	rpm-specfile, rpm, spec, rpm-specspecfile
ตัวพิมพ์เล็ก	ruby, rb, gemspec, podspec, thorirb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, , stepstp
Scala	scala
ชุดรูปแบบ	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Shell	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Structured Text	iecst, , scl, stlstructured-text
Stylus	stylus, styl
SubUnit	subunit
Supercollider	supercollider, sc
Swift	swift
Tcl	tcl, tk
Terraform (HCL)	terraform, , tfhcl
Test Anything Protocol	tap
TeX	tex
Thrift	thrift
TOML	toml
TP	tp
Twig	twig, craftcms
TypeScript	typescript, ts
VB.NET	vbnet, vb
VBScript	vbscript, vbs
VHDL	vhdl
Vala	vala
Verilog	verilog, v
Vim Script	vim
Visual Basic	vb
Visual Basic สำหรับแอปพลิเคชัน	vba
X ++	xpp
x86 Assembly	x86asm
XL	xl, tao
XQuery	xquery, , xpathxq
XAML	xaml
XML	xml, xhtml, rss, atom, xjb, xsd, , xslplist
YAML	yml, yaml
Zephir	zephir, zep

เคล็ดลับ

คุณลักษณะ Learn Authoring Pack คุณลักษณะ การดําเนินการ Dev Lang ให้เสร็จสิ้น ใช้นามแฝงที่ถูกต้องอันแรกเมื่อมีนามแฝงอยู่หลายนามแฝง

ขั้นตอนถัดไป

สำหรับข้อมูลเกี่ยวกับการจัดรูปแบบข้อความสำหรับชนิดเนื้อหาอื่นนอกเหนือจากโค้ด ให้ดู แนวทางการจัดรูปแบบข้อความ