File globbing di .NET

Dalam tulisan ini, Anda akan mempelajari cara menggunakan file globbing dengan paket NuGet 📦 Microsoft.Extensions.FileSystemGlobbing. Glob adalah istilah yang digunakan untuk menentukan pola untuk mencocokkan nama file dan direktori berdasarkan kartubebas. Globbing adalah tindakan menentukan satu atau beberapa pola glob yang merupakan pencocokan inklusif atau eksklusif, dan menghasilkan berkas dari kecocokan tersebut.

Pola

Untuk mencocokkan file dalam sistem file berdasarkan pola yang ditentukan pengguna, mulailah dengan menginstansiasi objek Matcher. Matcher dapat dibuat tanpa parameter, atau dengan System.StringComparison parameter, yang digunakan secara internal untuk membandingkan pola dengan nama file. Matcher mengekspos metode-metode aditif berikut:

• Matcher.AddExclude
• Matcher.AddInclude

Metode AddExclude dan AddInclude dapat dipanggil berapa kali pun, untuk menambahkan berbagai pola nama file yang akan dikecualikan atau disertakan dalam hasil. Setelah Anda menginstansiasi Matcher dan menambahkan pola, pola tersebut kemudian digunakan untuk mengevaluasi kecocokan dari direktori awal dengan metode Matcher.Execute.

Metode ekstensi

Objek Matcher memiliki beberapa metode ekstensi.

Beberapa pengecualian

Untuk menambahkan beberapa pola pengecualian, Anda dapat menggunakan:

Matcher matcher = new();
matcher.AddExclude("*.txt");
matcher.AddExclude("*.asciidoc");
matcher.AddExclude("*.md");

Atau, Anda dapat menggunakan MatcherExtensions.AddExcludePatterns(Matcher, IEnumerable<String>[]) untuk menambahkan beberapa pola pengecualian dalam satu panggilan:

Matcher matcher = new();
matcher.AddExcludePatterns(new [] { "*.txt", "*.asciidoc", "*.md" });

Metode ekstensi ini melakukan iterasi atas semua pola yang disediakan yang memanggil AddExclude atas nama Anda.

Beberapa penyertaan

Untuk menambahkan beberapa pola pencakupan, Anda dapat menggunakan:

Matcher matcher = new();
matcher.AddInclude("*.txt");
matcher.AddInclude("*.asciidoc");
matcher.AddInclude("*.md");

Atau Anda dapat menggunakan MatcherExtensions.AddIncludePatterns(Matcher, IEnumerable<String>[]) untuk menambahkan beberapa pola penyertaan dalam satu panggilan.

Matcher matcher = new();
matcher.AddIncludePatterns(new[] { "*.txt", "*.asciidoc", "*.md" });

Metode ekstensi ini melakukan iterasi atas semua pola yang disediakan yang memanggil AddInclude atas nama Anda.

Dapatkan semua file yang cocok

Untuk mendapatkan semua file yang cocok, Anda harus memanggil Matcher.Execute(DirectoryInfoBase) secara langsung atau tidak langsung. Untuk memanggilnya secara langsung, Anda memerlukan direktori pencarian:

Matcher matcher = new();
matcher.AddIncludePatterns(new[] { "*.txt", "*.asciidoc", "*.md" });

string searchDirectory = "../starting-folder/";

PatternMatchingResult result = matcher.Execute(
    new DirectoryInfoWrapper(
        new DirectoryInfo(searchDirectory)));

// Use result.HasMatches and results.Files.
// The files in the results object are file paths relative to the search directory.

Kode C# sebelumnya:

• Menginstansiasi objek Matcher.
• Memanggil fungsi AddIncludePatterns(Matcher, IEnumerable<String>[]) untuk menambahkan pola nama file yang akan disertakan.
• Mendeklarasikan dan menetapkan nilai direktori pencarian.
• Membuat instans DirectoryInfo dalam searchDirectory yang diberikan.
• DirectoryInfoWrapper Menginstansiasi dari DirectoryInfo yang dibungkusnya.
• Memanggil Execute dengan instans DirectoryInfoWrapper untuk menghasilkan objek PatternMatchingResult.

Catatan

DirectoryInfoWrapper Tipe didefinisikan dalam Microsoft.Extensions.FileSystemGlobbing.Abstractions namespace, dan DirectoryInfo tipe didefinisikan dalam System.IO namespace. Untuk menghindari arahan yang tidak perlu using , Anda dapat menggunakan metode ekstensi yang disediakan.

Ada metode ekstensi lain yang menghasilkan IEnumerable<string> yang mewakili file yang cocok:

Matcher matcher = new();
matcher.AddIncludePatterns(new[] { "*.txt", "*.asciidoc", "*.md" });

string searchDirectory = "../starting-folder/";

IEnumerable<string> matchingFiles = matcher.GetResultsInFullPath(searchDirectory);

// Use matchingFiles if there are any found.
// The files in this collection are fully qualified file system paths.

Kode C# sebelumnya:

• Menginstansiasi objek Matcher.
• Memanggil fungsi AddIncludePatterns(Matcher, IEnumerable<String>[]) untuk menambahkan pola nama file yang akan disertakan.
• Mendeklarasikan dan menetapkan nilai direktori pencarian.
• Memanggil GetResultsInFullPath dengan nilai searchDirectory untuk menghasilkan semua file yang cocok sebagai IEnumerable<string>.

Mencocokkan kelebihan beban

Objek PatternMatchingResult mewakili kumpulan FilePatternMatch instance, dan menunjukkan nilai boolean apakah hasilnya memiliki kecocokan—PatternMatchingResult.HasMatches.

Dengan instance Matcher, Anda dapat memanggil salah satu dari berbagai metode overload Match untuk mendapatkan hasil pola yang cocok. Metode Match membalikkan tanggung jawab kepada pemanggil untuk menyediakan file atau kumpulan file guna memeriksa kecocokan. Dengan kata lain, pemanggil bertanggung jawab untuk memberikan file yang akan dicocokkan.

Penting

Saat menggunakan salah satu metode Match overload, tidak ada I/O sistem file yang terlibat. Semua globbing file dilakukan dalam memori dengan menyertakan dan mengecualikan matcher pola instans. Parameter-parameter Match overload tidak harus berupa jalur yang sepenuhnya memenuhi syarat. Direktori saat ini (Directory.GetCurrentDirectory()) digunakan ketika tidak ditentukan.

Untuk mencocokkan satu file:

Matcher matcher = new();
matcher.AddInclude("**/*.md");

PatternMatchingResult result = matcher.Match("file.md");

Kode C# sebelumnya:

• Mencocokkan file mana pun dengan ekstensi file .md pada kedalaman direktori arbitrer.
• Jika file bernama file.md ada di subdirektori dari direktori saat ini:
  • result.HasMatches akan menjadi true.
  • dan result.Files akan memiliki satu kecocokan.

Kelebihan beban tambahan Match berfungsi dengan cara yang sama.

Evaluasi yang diurutkan dari include/exclude

Secara bawaan, matcher mengevaluasi semua pola yang disertakan terlebih dahulu, lalu menerapkan semua pola pengecualian, tanpa memandang urutan penambahannya. Ini berarti Anda tidak dapat menyertakan kembali file yang sebelumnya dikecualikan.

Mulai dari versi 10 paket 📦, Anda dapat memilih untuk menggunakan evaluasi terurut, di mana elemen yang dimasukkan dan dikecualikan diproses tepat sesuai urutan penambahannya:

using Microsoft.Extensions.FileSystemGlobbing;

// Preserve the order of patterns when matching.
Matcher matcher = new(preserveFilterOrder: true);

matcher.AddInclude("**/*");                // include everything
matcher.AddExclude("logs/**/*");           // exclude logs
matcher.AddInclude("logs/important/**/*"); // re-include important logs

var result = matcher.Execute(new DirectoryInfoWrapper(new DirectoryInfo(root)));
foreach (var file in result.Files)
{
    Console.WriteLine(file.Path);
}

Dalam mode ini, pola diterapkan satu demi satu:

• **/* menambahkan semua file.
• logs/**/* memfilter apa pun di logs/.
• logs/important/**/* menambahkan kembali hanya file di bawah logs/important/.

Kode yang ada yang menggunakan konstruktor default akan terus berjalan dengan perilaku asli "semua termasuk, lalu semua mengecualikan".

Format pola

Pola yang ditentukan dalam AddExclude metode dan AddInclude dapat menggunakan format berikut untuk mencocokkan beberapa file atau direktori.

• Direktori atau nama file yang tepat

  • some-file.txt
  • path/to/file.txt

• Karakter pengganti * dalam nama file dan direktori yang mewakili nol hingga banyak karakter tidak termasuk karakter-karakter pemisah.

  Nilai	Deskripsi
  *.txt	Semua file dengan ekstensi file .txt .
  *.*	Semua file dengan ekstensi tertentu.
  *	Semua file dalam direktori tingkat atas.
  .*	Nama file dimulai dengan '.'.
  *word*	Semua file dengan 'word' dalam nama file.
  readme.*	Semua file bernama 'readme' dengan ekstensi file apa pun.
  styles/*.css	Semua file dengan ekstensi '.css' di direktori 'styles/'.
  scripts/*/*	Semua file dalam 'scripts/' atau satu tingkat subdirektori di bawah 'scripts/'.
  images*/*	Semua file dalam folder dengan nama atau dimulai dengan 'gambar'.

• Kedalaman direktori sewenang-wenang (/**/).

  Nilai	Deskripsi
  **/*	Semua file dalam subdirektori apa pun.
  dir/	Semua file dalam subdirektori apa pun di bawah 'dir/'.
  dir/**/*	Semua file dalam subdirektori apa pun di bawah 'dir/'.

• Jalur relatif.

  Untuk mencocokkan semua file dalam direktori bernama "shared" pada level yang sama dengan direktori dasar yang diberikan kepada Matcher.Execute(DirectoryInfoBase), gunakan ../shared/*.

Contoh

Pertimbangkan contoh direktori berikut, dan setiap file dalam folder yang sesuai.

📁 parent
│    file.md
│    README.md
│
└───📁 child
    │    file.MD
    │    index.js
    │    more.md
    │    sample.mtext
    │
    ├───📁 assets
    │        image.png
    │        image.svg
    │
    └───📁 grandchild
             file.md
             style.css
             sub.text

Petunjuk / Saran

Beberapa ekstensi file dalam huruf besar, sementara yang lain dalam huruf kecil. Secara default, StringComparer.OrdinalIgnoreCase digunakan. Untuk menentukan perilaku perbandingan string yang berbeda, gunakan Matcher.Matcher(StringComparison) konstruktor.

Untuk mendapatkan semua file markdown, di mana ekstensi file adalah .md atau .mtext, tanpa mempedulikan huruf besar atau kecil.

Matcher matcher = new();
matcher.AddIncludePatterns(new[] { "**/*.md", "**/*.mtext" });

foreach (string file in matcher.GetResultsInFullPath("parent"))
{
    Console.WriteLine(file);
}

Menjalankan aplikasi akan menghasilkan hasil yang mirip dengan yang berikut:

C:\app\parent\file.md
C:\app\parent\README.md
C:\app\parent\child\file.MD
C:\app\parent\child\more.md
C:\app\parent\child\sample.mtext
C:\app\parent\child\grandchild\file.md

Untuk mendapatkan file apa pun di direktori assets pada kedalaman arbitrer:

Matcher matcher = new();
matcher.AddInclude("**/assets/**/*");

foreach (string file in matcher.GetResultsInFullPath("parent"))
{
    Console.WriteLine(file);
}

Menjalankan aplikasi akan menghasilkan hasil yang mirip dengan yang berikut:

C:\app\parent\child\assets\image.png
C:\app\parent\child\assets\image.svg

Untuk mendapatkan file apa pun di mana nama direktori berisi kata anak pada kedalaman arbitrer, dan ekstensi file bukan .md, .text, atau .mtext:

Matcher matcher = new();
matcher.AddInclude("**/*child/**/*");
matcher.AddExcludePatterns(
    new[]
    {
        "**/*.md", "**/*.text", "**/*.mtext"
    });

foreach (string file in matcher.GetResultsInFullPath("parent"))
{
    Console.WriteLine(file);
}

Menjalankan aplikasi akan menghasilkan hasil yang mirip dengan yang berikut:

C:\app\parent\child\index.js
C:\app\parent\child\assets\image.png
C:\app\parent\child\assets\image.svg
C:\app\parent\child\grandchild\style.css

Lihat juga

• Gambaran umum pustaka runtime
• File dan Stream I/O