Πώς μπορείτε να συμπεριλάβετε κώδικα στην τεκμηρίωση

Υπάρχουν πολλοί τρόποι εκτός από στιγμιότυπα οθόνης για να συμπεριλάβετε κώδικα σε ένα άρθρο που δημοσιεύεται στο 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 θα πρέπει να θεωρούνται κώδικας. Όταν έχετε αμφιβολίες, ανατρέξτε στην ενότητα Οδηγίες μορφοποίησης κειμένου.

Ενσωματωμένο στυλ κώδικα

Για να συμπεριλάβετε ένα στοιχείο κώδικα σε κείμενο άρθρου, περικλείστε το σε βαρείες (') για να υποδείξετε στυλ κώδικα. Το ενσωματωμένο στυλ κώδικα δεν θα πρέπει να χρησιμοποιεί τη μορφή τριπλής βαρείας.

Σήμανση	Αποδίδεται
Από προεπιλογή, το Πλαίσιο οντοτήτων ερμηνεύει μια ιδιότητα που ονομάζεται "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> είναι η ομάδα πόρων όπου...

Οι άγκιστρα { } δεν συνιστάται να χρησιμοποιηθούν ως σύμβολα κράτησης θέσης ως συμβάματα κράτησης θέσης. Μπορεί να συγχέονται με την ίδια σημειογραφία που χρησιμοποιείται σε κείμενο με δυνατότητα αντικατάστασης, συμβολοσειρές μορφοποίησης, παρεμβολή συμβολοσειρών, πρότυπα κειμένου και παρόμοιες κατασκευές προγραμματισμού.

Τα ονόματα συμβόλων κράτησης θέσης μπορούν να διαχωρίζονται με παύλες ("υπόθεση κεμπάπ"), με χαρακτήρες υπογράμμισης ή να μην διαχωρίζονται καθόλου (υπόθεση Pascal). Η υπόθεση κεμπάπ μπορεί να δημιουργήσει σφάλματα σύνταξης και οι χαρακτήρες υπογράμμισης ενδέχεται να έρχονται σε διένεξη με υπογράμμιση. Τα κεφαλαία ενδέχεται να έρχονται σε διένεξη με επώνυμες σταθερές σε πολλές γλώσσες, παρόλο που μπορεί επίσης να τραβήξει την προσοχή στο όνομα κράτησης θέσης.

<Resource-Group-Name> ή <ResourceGroupName>

Στοιχεία επιπέδου μπλοκ κώδικα

Η σύνταξη για τον συμπερίληψη κώδικα σε ένα έγγραφο εξαρτάται από το σημείο όπου βρίσκεται ο κώδικας:

• Στο αρχείο Markdown του άρθρου
• Σε ένα αρχείο κώδικα στο ίδιο αποθετήριο δεδομένων
• Σε ένα αρχείο κώδικα σε διαφορετικό αποθετήριο δεδομένων

Ακολουθούν οι οδηγίες που ισχύουν και για τους τρεις τύπους στοιχείων επιπέδου μπλοκ κώδικα:

• Screenshots
• Αυτοματοποίηση επικύρωσης κώδικα
• Επισήμανση βασικών γραμμών κώδικα
• Αποφυγή οριζόντιων γραμμών κύλισης
• Σαφής προσδιορισμός εσφαλμένου κώδικα

Στιγμιότυπα οθόνης

Όλες οι μέθοδοι που παρατίθενται στην προηγούμενη ενότητα έχουν ως αποτέλεσμα στοιχεία επιπέδου μπλοκ κώδικα που μπορούν να χρησιμοποιηθούν:

• Μπορείτε να αντιγράψετε και να επικολλήσετε από αυτά.
• Καταχωρούνται στο ευρετήριο από μηχανές αναζήτησης.
• Είναι προσβάσιμα από προγράμματα ανάγνωσης οθόνης.

Αυτοί είναι μόνο μερικοί από τους λόγους για τους οποίους τα στιγμιότυπα οθόνης IDE δεν συνιστώνται ως μέθοδος συμπερίληψης κώδικα σε άρθρο. Χρησιμοποιήστε στιγμιότυπα οθόνης IDE για κώδικα μόνο εάν εμφανίζετε κάτι σχετικά με το ίδιο το IDE, όπως το IntelliSense. Μην χρησιμοποιείτε στιγμιότυπα οθόνης μόνο για την εμφάνιση χρωματισμού και επισήμανσης.

Επικύρωση κώδικα

Ορισμένα αποθετήρια δεδομένων έχουν υλοποιήσει διεργασίες που μεταγλωττίζουν αυτόματα όλα τα δείγματα κώδικα για να πραγματοποιήσουν έλεγχο για σφάλματα. Το αποθετήριο δεδομένων .NET το κάνει αυτό. Για περισσότερες πληροφορίες, ανατρέξτε στην ενότητα Συνεισφορά στο αποθετήριο δεδομένων .NET.

Εάν συμπεριλαμβάνετε στοιχεία επιπέδου μπλοκ κώδικα από άλλο αποθετήριο δεδομένων, συνεργαστείτε με τους κατόχους σε μια στρατηγική συντήρησης για τον κώδικα, ώστε ο συμπεριλαμβανόμενος κώδικάς σας να μην διακοπεί ή πάψει να είναι ενημερωμένος καθώς αποστέλλονται οι νέες εκδόσεις των βιβλιοθηκών που χρησιμοποιεί ο κώδικας.

Επισήμανση

Τα τμήματα κώδικα συνήθως περιλαμβάνουν περισσότερο κώδικα από όσο απαιτείται, ώστε να παρέχουν το περιβάλλον. Βοηθά την αναγνωσιμότητα όταν επισημαίνετε τις βασικές γραμμές στις οποίες επικεντρώνεστε στο τμήμα κώδικα, όπως σε αυτό το παράδειγμα:

Δεν μπορείτε να επισημάνετε κώδικα όταν τον συμπεριλαμβάνετε στο αρχείο Markdown του άρθρου. Λειτουργεί μόνο για τμήματα κώδικα που συμπεριλαμβάνονται με χρήση αναφοράς σε ένα αρχείο κώδικα.

Οριζόντιες γραμμές κύλισης

Χωρίστε τις μεγάλες γραμμές για να αποφύγετε τις οριζόντιες γραμμές κύλισης. Οι γραμμές κύλισης στα στοιχεία επιπέδου μπλοκ κώδικα καθιστούν δυσανάγνωστο τον κώδικα. Είναι ιδιαίτερα προβληματικές σε στοιχεία επιπέδου μπλοκ κώδικα μεγαλύτερου μήκους, όπου μπορεί να είναι αδύνατη η εμφάνιση της γραμμής κύλισης και της γραμμής που θέλετε να διαβάσετε ταυτόχρονα.

Μια καλή πρακτική για την ελαχιστοποίηση των οριζόντιων γραμμών κύλισης στα στοιχεία επιπέδου μπλοκ κώδικα είναι να χωρίζετε τις γραμμές κώδικα που είναι μεγαλύτερες από 85 χαρακτήρες. Ωστόσο, έχετε υπόψη ότι η παρουσία ή η απουσία μιας γραμμής κύλισης δεν είναι το μοναδικό κριτήριο αναγνωσιμότητας. Εάν το να χωρίσετε μια γραμμή πριν από τους 85 χαρακτήρες βλάπτει την αναγνωσιμότητα ή την ευκολία αντιγραφής-επικόλλησης, μην διστάσετε να ξεπεράσετε τους 85 χαρακτήρες.

Σαφής προσδιορισμός εσφαλμένου κώδικα

Σε ορισμένα σενάρια, είναι χρήσιμο να επισημάνετε μοτίβα κωδικοποίησης που θα πρέπει να αποφεύγονται, για παράδειγμα:

• Κώδικας που θα προκαλέσει σφάλμα στο πρόγραμμα μεταγλώττισης, εάν επιχειρήσετε.
• Κώδικας που θα μεταγλωττιστεί σωστά, αλλά δεν συνιστάται.

Για αυτά τα σενάρια:

• Εξηγήστε το σφάλμα τόσο στα σχόλια κώδικα όσο και στο κείμενο του άρθρου.

  Οι αναγνώστες συχνά παραλείπουν το κείμενο του άρθρου και κοιτάζουν μόνο κώδικα, επομένως δεν αρκεί να εξηγήσουμε το σφάλμα μόνο στο κείμενο του άρθρου. Επίσης, δεν αρκεί να εξηγήσουμε το σφάλμα μόνο σε σχόλια κώδικα, επειδή τα σχόλια κώδικα δεν μεταφρασμένα.

• Εξετάστε το ενδεχόμενο να σχολιάσετε τον κώδικα εάν αυτό θα προκαλούσε σφάλμα μεταγλωττιστή.

  Ο κώδικας που έχει σχολιάσει δεν θα διακόψει το σύστημα συνεχούς ενοποίηση (CI) εάν το αποθετήριο δεδομένων του άρθρου έχει ένα τώρα ή υλοποιήσει ένα στο μέλλον.

Για ένα παράδειγμα του τρόπου παρουσίασης κώδικα που δεν συνιστάται, ανατρέξτε στο παράδειγμα χρήσης Εκτέλεση: αλλαγή πεζών-γραμμάτων. Σε αυτό το παράδειγμα, η συμβουλή για να το αποφύγετε είναι ενσωματωμένη ακόμη και στον ίδιο τον κώδικα, καθώς το όνομα της μεθόδου 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, βεβαιωθείτε ότι δεν περιέχει "καλλιγραφικά εισαγωγικά", τα οποία δεν είναι έγκυρα στον κώδικα. Εάν περιέχει, αλλάξτε τα σε κανονικά εισαγωγικά (' και "). Εναλλακτικά, βασιστείτε στη δυνατότητα αντικατάστασης καλλιγραφημάτων καλλιγραφικά εισαγωγικά του Learn Authoring Pack.

Αναφορές τμήματος κώδικα εντός αποθετηρίου δεδομένων

Ο προτιμώμενος τρόπος για να συμπεριλάβετε τμήματα κώδικα για γλώσσες προγραμματισμού σε έγγραφα είναι με χρήση αναφοράς σε ένα αρχείο κώδικα. Αυτή η μέθοδος σάς δίνει τη δυνατότητα να επισημάνετε γραμμές κώδικα και καθιστά το ευρύτερο περιβάλλον του τμήματος κώδικα διαθέσιμο στο GitHub για να το χρησιμοποιήσουν οι προγραμματιστές. Μπορείτε να συμπεριλάβετε κώδικα χρησιμοποιώντας τη μορφή τριπλής άνω και κάτω τελείας (:::) είτε με μη αυτόματο τρόπο είτε στο Visual Studio Code με τη βοήθεια του πακέτου σύνταξης του Learn.

1. Στο Visual Studio Code, πατήστε Alt + M ή Option + M και επιλέξτε "Απόσπασμα".
2. Όταν επιλέξετε "Απόσπασμα", θα σας ζητηθεί να επιλέξετε "Πλήρης αναζήτηση", "Αναζήτηση σε εμβέλεια" ή "Αναφορά μεταξύ αποθετηρίων". Για να κάνετε αναζήτηση τοπικά, επιλέξτε "Πλήρης αναζήτηση".
3. Καταχωρήστε έναν όρο αναζήτησης για να εντοπίσετε το αρχείο. Όταν εντοπίσετε το αρχείο, επιλέξτε το.
4. Στη συνέχεια, κάντε μια επιλογή για να προσδιορίσετε τις γραμμές κώδικα που θέλετε να συμπεριληφθούν στο απόσπασμα. Οι επιλογές είναι: Αναγνωριστικό, Περιοχή και Καμία.
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.

1. Στο Visual Studio Code, πατήστε Alt + M ή Option + M και επιλέξτε "Απόσπασμα".
2. Όταν επιλέξετε "Απόσπασμα", θα σας ζητηθεί να επιλέξετε "Πλήρης αναζήτηση", "Αναζήτηση σε εμβέλεια" ή "Αναφορά μεταξύ αποθετηρίων". Για αναζήτηση σε πολλαπλά αποθετήρια, επιλέξτε "Αναφορά μεταξύ αποθετηρίων".
3. Θα εμφανιστούν τα αποθετήρια που βρίσκονται στο .openpublishing.publish.config.json. Επιλέξτε ένα αποθετήριο.
4. Καταχωρήστε έναν όρο αναζήτησης για να εντοπίσετε το αρχείο. Όταν εντοπίσετε το αρχείο, επιλέξτε το.
5. Στη συνέχεια, κάντε μια επιλογή για να προσδιορίσετε τις γραμμές κώδικα που θέλετε να συμπεριληφθούν στο απόσπασμα. Οι επιλογές είναι: Αναγνωριστικό, Περιοχή και Καμία.
6. Με βάση την επιλογή σας στο Βήμα 5, καταχωρήστε μια τιμή.

Η αναφορά αποσπάσματος έχει την εξής μορφή:

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

Στο αποθετήριο δεδομένων azure-functions-durable-extension, αυτό το αρχείο κώδικα βρίσκεται στον φάκελο samples/csx/shared. Όπως σημειώθηκε προηγουμένως, οι αριθμοί γραμμών προς επισήμανση είναι σχετικοί με την αρχή του τμήματος κώδικα αντί για την αρχή του αρχείου.

Σημείωμα

Το όνομα που αντιστοιχίζετε στο εξαρτώμενο αποθετήριο είναι σχετικό με τη ρίζα του κύριου αποθετηρίου δεδομένων, αλλά η περιπωλίδα (~) αναφέρεται στη ρίζα του συνόλου εγγράφων. Η ρίζα του συνόλου εγγράφων καθορίζεται από build_source_folder το στο .openpublishing.publish.config.json. Η διαδρομή προς το τμήμα κώδικα στο προηγούμενο παράδειγμα λειτουργεί στο αποθετήριο δεδομένων του azure-docs, επειδή 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. Στα μετα-δεδομένα κελιού, προσθέστε ένα χαρακτηριστικό "name":

   "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 Το αναγνωριστικό του τμήματος κώδικα που πρέπει να εισαχθεί από το αρχείο κώδικα. Αυτή η τιμή δεν μπορεί να συνυπάρχει με την περιοχή.
    • highlight: 2-4,6 Η περιοχή ή/και οι αριθμοί γραμμών που πρέπει να επισημανθούν στο δημιουργημένο απόσπασμα κώδικα. Η αρίθμηση είναι σχετική με τις γραμμές που εμφανίζονται (όπως καθορίζεται από την περιοχή ή το αναγνωριστικό) και όχι με το αρχείο.
    • 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
Συναρμολογητής (assembler) ARM	armasm, arm
Συναρμολογητής (assembler) AVR	avrasm
ActionScript	actionscript, as
Χρυσόστομος	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, nawk, gawk
Axapta	axapta
AzCopy	azcopy
Azure CLI	azurecli
Azure CLI (αλληλεπιδραστική)	azurecli-interactive
Azure PowerShell	azurepowershell
Azure PowerShell (αλληλεπιδραστική)	azurepowershell-interactive
Bash	bash, sh, zsh
Βασική	basic
BNF	bnf
Ε	c
C#	csharp, cs
C# (αλληλεπιδραστική)	csharp-interactive
C++	cpp, , ccc, h, , c++, h++,hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Δέσμη ενεργειών αντικειμένου cache	cos, cls
CMake	cmake, cmake.in
Coq	coq
CSP	csp
CSS	css
Cap'n Proto	capnproto, capnp
Clojure	clojure, clj
CoffeeScript	coffeescript, coffee, cson, iced
Crmsh	crmsh, crm, pcmk
Crystal	crystal, cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
Αρχείο ζώνης DNS	dns, zone, bind
DOS	dos, bat, cmd
Dart	dart
Delphi	delphi, , dfmdpr, pas, , pascal, freepascal, lazarus, , , , lprlfm
Diff	diff, patch
Django	django, jinja
Dockerfile	dockerfile, docker
dsconfig	dsconfig
DTS (Δέντρο συσκευής)	dts
Dust	dust, dst
Νίκος	dylan
EBNF	ebnf
Elixir	elixir
Elm	elm
Erlang	erlang, erl
Excel	excel, xls, xlsx
Extempore	extempore, xtlang, xtm
F#	fsharp, fs
FIX	fix
Fortran	fortran, f90, f95
G-Code	gcode, nc
Gams	gams, gms
GAUSS	gauss, gss
GDScript	godot, gdscript
Gherkin	gherkin
GN για Ninja	gn, gni
Go	go, golang
Golo	golo, gololang
Gradle	gradle
GraphQL	graphql
Groovy	groovy
HTML	html, xhtml
HTTP	http, https
Haml	haml
Λαβές	handlebars, hbs, html.hbs, html.handlebars
Haskell	haskell, hs
Haxe	haxe, hx
Hy	hy, hylang
Ini	ini
Inform7	inform7, i7
IRPF90	irpf90
JSON	json
Java	java, jsp
Javascript	javascript, js, jsx
Kotlin	kotlin, kt
Kusto	kusto
Leaf	leaf
Lasso	lasso, ls, lassoscript
Less	less
LDIF	ldif
Lisp	lisp
Διακομιστής LiveCode	livecodeserver
LiveScript	livescript, ls
Lua	lua
Makefile	makefile, mk, mak
Σήμανση	markdown, md, mkdown, mkd
Mathematica	mathematica, mma, wl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
Γλώσσα δημιουργίας δεσμών ενεργειών mIRC	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, objc, obj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad, scad
Γλώσσα κανόνα Oracle	ruleslanguage
Oxygene	oxygene
PF	pf, pf.conf
PHP	php, php3, php4, , php5php6
Parser3	parser3
Perl	perl, pl, pm
Απλό κείμενο χωρίς επισήμανση	plaintext
Pony	pony
PostgreSQL & PL/pgSQL	pgsql, postgres, postgresql
PowerShell	powershell, ps
PowerShell (αλληλεπιδραστική)	powershell-interactive
Επεξεργασία	processing
Prolog	prolog
Ιδιότητες	properties
Buffer πρωτοκόλλων	protobuf
Puppet	puppet, pp
Python	python, py, gyp
Αποτελέσματα προγράμματος δημιουργίας προφίλ Python	profile
Q#	qsharp
Q	k, kdb
QML	qml
R	r
Razor CSHTML	cshtml, razor, razor-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	ruby, , rbgemspec, , , thorpodspecirb
Rust	rust, rs
SAS	SAS, sas
SCSS	scss
SQL	sql
STEP Part 21	p21, step, stp
Scala	scala
Σχήμα	scheme
Scilab	scilab, sci
Shape Expressions	shexc
Κέλυφος	shell, console
Smali	smali
Smalltalk	smalltalk, st
Solidity	solidity, sol
Stan	stan
Stata	stata
Structured Text	iecst, scl, stl, structured-text
Stylus	stylus, styl
SubUnit	subunit
Supercollider	supercollider, sc
Swift	swift
Tcl	tcl, tk
Terraform (HCL)	terraform, tf, hcl
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 for Applications	vba
X++	xpp
x86 Assembly	x86asm
XL	xl, tao
XQuery	xquery, xpath, xq
XAML	xaml
Xml	xml, , rssxhtml, atom, , xjb, xsd, , , xslplist
YAML	yml, yaml
Zephir	zephir, zep

Φιλοδώρημα

Η δυνατότητα Ολοκλήρωση γλώσσας γλώσσας του Learn Authoring Pack χρησιμοποιεί το πρώτο έγκυρο ψευδώνυμο όταν υπάρχουν διαθέσιμα πολλά ψευδώνυμα.

Επόμενα βήματα

Για πληροφορίες σχετικά με τη μορφοποίηση κειμένου για τύπους περιεχομένου εκτός από κώδικα, ανατρέξτε στο θέμα Οδηγίες μορφοποίησης κειμένου.