Menggunakan ekstensi Cookiecutter

Cookiecutter menyediakan antarmuka pengguna grafis untuk menemukan templat, opsi templat input, dan membuat proyek dan file. Visual Studio 2017 dan yang lebih baru menyertakan ekstensi Cookiecutter. Ini dapat diinstal secara terpisah di versi Visual Studio yang lebih lama.

Di Visual Studio, ekstensi Cookiecutter tersedia di bawah Lihat>Cookiecutter Explorer:

Prasyarat

• Visual Studio. Untuk menginstal produk, ikuti langkah-langkah di Menginstal Visual Studio.

• Python 3.3 atau yang lebih baru (32-bit atau 64-bit) atau Anaconda 3 4.2 atau yang lebih baru (32-bit atau 64-bit).

  • Jika penerjemah Python yang sesuai tidak tersedia, Visual Studio menampilkan peringatan.

  • Jika Anda menginstal penerjemah Python saat Visual Studio berjalan, pilih opsi Beranda pada toolbar Cookiecutter Explorer untuk mendeteksi penerjemah yang baru diinstal. Untuk informasi selengkapnya, lihat Membuat dan mengelola lingkungan Python di Visual Studio.

Bekerja dengan Cookiecutter Explorer

Di Cookiecutter Explorer, Anda dapat menelusuri dan memilih templat, mengkloning templat ke komputer lokal Anda, mengatur opsi templat, dan membuat kode dari templat.

Telusuri templat

Anda dapat menelusuri templat di Cookiecutter Explorer untuk melihat apa yang sudah diinstal dan apa yang tersedia.

1. Di Cookiecutter Explorer, pilih opsi Beranda pada toolbar untuk melihat templat yang tersedia.

   

   Beranda menampilkan daftar templat untuk dipilih, diatur ke dalam empat grup yang mungkin:

   Grupkan	Deskripsi	Catatan
   Terinstal	Templat terinstal ke komputer lokal Anda. Ketika templat online digunakan, repositorinya secara otomatis dikloning ke subfolder ~/.cookiecutters.	Anda dapat menghapus templat yang diinstal dari sistem Anda dengan memilih Hapus pada toolbar Cookiecutter Explorer.
   Direkomendasikan	Templat yang dimuat dari umpan yang direkomendasikan. Microsoft mengumpulkan umpan default.	Anda dapat menyesuaikan umpan dengan mengikuti langkah-langkah dalam mengatur opsi Cookiecutter.
   GitHub	Hasil pencarian GitHub untuk kata kunci "cookiecutter". Daftar repositori git dikembalikan dalam bentuk paginated.	Saat daftar hasil melebihi tampilan saat ini, Anda dapat memilih opsi Muat Lainnya untuk menampilkan kumpulan hasil paginasi berikutnya dalam daftar.
   Adat	Templat kustom apa pun yang ditentukan melalui Cookiecutter Explorer. Saat lokasi templat kustom dimasukkan di kotak pencarian Cookiecutter Explorer , lokasi muncul di grup ini.	Anda dapat menentukan templat kustom dengan memasukkan jalur lengkap ke repositori git, atau jalur lengkap ke folder di disk lokal Anda.

2. Untuk memperlihatkan atau menyembunyikan daftar templat yang tersedia untuk kategori tertentu, pilih panah di samping kategori.

Mengkloning templat

Anda dapat bekerja dengan templat yang tersedia di Cookiecutter Explorer untuk membuat salinan lokal agar berfungsi.

1. Di Cookiecutter Explorer, pilih templat. Informasi tentang templat yang dipilih ditampilkan di bagian bawah halaman beranda Cookiecutter Explorer .

   

   Ringkasan templat menyertakan tautan untuk informasi selengkapnya tentang templat. Anda dapat membuka halaman repositori GitHub untuk templat, melihat wiki templat, atau menemukan Masalah yang dilaporkan.

2. Untuk mengkloning templat yang dipilih, pilih Berikutnya. Cookiecutter membuat salinan lokal templat.

Perilaku kloning tergantung pada jenis templat yang Anda pilih:

Jenis template	Perilaku
Terinstal	Jika templat yang dipilih diinstal di sesi Visual Studio sebelumnya, templat akan dihapus secara otomatis dan versi terbaru diinstal dan dikloning di komputer lokal Anda.
Direkomendasikan	Templat yang dipilih dikloning dan diinstal pada komputer lokal Anda.
GitHub	Templat yang dipilih dikloning dan diinstal pada komputer lokal Anda.
Pencarian kustom	- URL: Jika Anda memasukkan URL kustom untuk repositori git ke dalam kotak pencarian Cookiecutter Explorer , lalu pilih templat, templat yang dipilih akan dikloning dan diinstal di komputer lokal Anda. - Jalur folder: Jika Anda memasukkan jalur folder kustom ke dalam kotak pencarian, dan memilih templat, Visual Studio memuat templat tersebut tanpa mengkloning.

Penting

Templat cookiecutter dikloning di bawah satu folder ~/.cookiecutters. Setiap subfolder diberi nama sesuai dengan nama repositori git, yang tidak menyertakan nama pengguna GitHub. Konflik dapat muncul jika Anda mengkloning templat yang berbeda dengan nama yang sama yang berasal dari penulis yang berbeda. Dalam hal ini, Cookiecutter mencegah Anda menimpa templat yang ada dengan templat yang berbeda dengan nama yang sama. Untuk menginstal templat lainnya, Anda harus menghapus templat yang sudah ada terlebih dahulu.

Mengatur opsi templat

Setelah Anda menginstal dan mengkloning templat secara lokal, Cookiecutter menampilkan halaman Opsi . Pada halaman ini, Anda dapat menentukan pengaturan, seperti lokasi jalur folder untuk file yang dihasilkan:

Setiap templat Cookiecutter mendefinisikan sekumpulan opsinya sendiri. Saat nilai default tersedia untuk pengaturan, halaman Opsi memperlihatkan teks yang disarankan di bidang terkait. Nilai default mungkin berupa cuplikan kode, seringkali ketika itu adalah nilai dinamis yang menggunakan opsi lain.

Untuk contoh ini, nama templat didefinisikan sebagai cookiecutter-flask/cookiecutter-flask. Saat nilai pengaturan dapat diubah, teks bidang tersedia untuk diedit.

1. Di bidang Buat ke, masukkan lokasi jalur folder untuk file apa pun yang dihasilkan oleh Cookiecutter.

2. Selanjutnya, atur opsi lain yang diinginkan untuk templat, seperti:

   • full_name: Nama lengkap yang akan diterapkan ke templat.
   • email: Alamat email pembuat templat.
   • github_username: Alias GitHub penulis templat.
   • python_version: Versi Python target untuk aplikasi web yang dibuat dari templat.

Mengatur default dengan file konfigurasi

Anda dapat menyesuaikan nilai default untuk opsi tertentu dengan file konfigurasi pengguna. Ketika ekstensi Cookiecutter mendeteksi file konfigurasi pengguna, ekstensi tersebut menimpa nilai default templat dengan nilai file konfigurasi. Untuk informasi selengkapnya tentang perilaku ini, lihat bagian Konfigurasi Pengguna dari dokumentasi Cookiecutter.

Menolak tugas yang ditentukan

Beberapa templat mengidentifikasi tugas Visual Studio tertentu untuk dijalankan setelah pembuatan kode. Tugas umum termasuk membuka browser web, membuka file di editor, dan menginstal dependensi. Saat templat mengidentifikasi tugas tertentu, pengaturan Jalankan tugas tambahan pada penyelesaian ditambahkan ke daftar opsi. Anda dapat mengonfigurasi pengaturan ini untuk memilih keluar dari tugas Visual Studio yang ditentukan.

Membuat kode dari templat

Setelah mengatur opsi templat, Anda siap untuk Cookiecutter membuat file proyek dan membuat kode.

Dialog menampilkan tombol setelah daftar opsi. Teks untuk tombol bergantung pada templat. Anda mungkin melihat Buat dan Buka folder, Tambahkan ke Solusi, dan sebagainya.

1. Pada halaman Opsi , pilih tombol yang mengikuti daftar opsi, seperti Buat dan Buka folder atau Tambahkan ke Solusi.

   

   Cookiecutter menghasilkan kode. Jika folder output tidak kosong, peringatan akan ditampilkan.

   • Jika Anda terbiasa dengan output templat dan tidak keberatan menimpa file, pilih OK untuk menutup peringatan.

   • Jika tidak, pilih Batal, tentukan folder kosong, lalu salin file yang dibuat secara manual ke folder output yang tidak ada.

2. Setelah Cookiecutter berhasil membuat file, Visual Studio membuka file proyek templat di Penjelajah Solusi.

Mengatur opsi Cookiecutter

Opsi Cookiecutter tersedia melaluiOpsi>Alat>Cookiecutter:

Opsi	Deskripsi
Periksa templat yang diperbarui	Mengontrol apakah Cookiecutter secara otomatis memeriksa secara online pembaruan pada templat yang diinstal.
URL umpan yang direkomendasikan	Lokasi file umpan templat yang direkomendasikan. Lokasi dapat berupa URL atau jalur ke file lokal. Biarkan URL kosong untuk menggunakan umpan yang dikumpulkan Microsoft default. Umpan menyediakan daftar lokasi templat sederhana, dipisahkan oleh baris baru. Untuk meminta perubahan pada umpan yang dikumpulkan, buat permintaan pull terhadap sumber di GitHub.
Tampilkan bantuan	Mengontrol visibilitas bilah informasi bantuan di bagian atas jendela Cookiecutter.

Mengoptimalkan templat Cookiecutter untuk Visual Studio

Ekstensi Cookiecutter untuk Visual Studio mendukung templat yang dibuat untuk Cookiecutter v1.4. Untuk informasi selengkapnya tentang penulisan templat Cookiecutter, lihat dokumentasi Cookiecutter.

Penyajian default variabel templat tergantung pada jenis data (string atau daftar):

• String: Jenis data String menggunakan label untuk nama variabel, kotak teks untuk memasukkan nilai, dan marka air yang memperlihatkan nilai default. Tipsalat pada kotak teks memperlihatkan nilai default.
• Daftar: Jenis data Daftar menggunakan label untuk nama variabel dan kotak kombo untuk memilih nilai. Tipsalat pada kotak kombo memperlihatkan nilai default.

Anda dapat meningkatkan penyajian dengan menentukan metadata lain dalam file cookiecutter.json Anda yang khusus untuk Visual Studio (dan diabaikan oleh Cookiecutter CLI). Semua properti bersifat opsional:

Properti	Deskripsi
label	Menentukan teks yang akan ditampilkan di atas editor untuk variabel, bukan nama variabel.
description	Menentukan tipsalat untuk ditampilkan pada kontrol edit, bukan nilai default untuk variabel tersebut.
url	Mengubah label menjadi hyperlink dengan tipsalat yang memperlihatkan URL. Memilih hyperlink akan membuka browser default pengguna ke URL tersebut.
selector	Memungkinkan penyesuaian editor untuk variabel. Pemilih berikut saat ini didukung: - string: Kotak teks standar, default untuk string. - list: Kotak kombo standar, default untuk daftar. - yesno: Kotak kombo untuk memilih antara y dan n, untuk string. - odbcConnection: Kotak teks dengan tombol elips (...) yang membuka dialog koneksi database.

Contoh berikut menunjukkan cara mengatur properti penyajian:

{
    "site_name": "web-app",
    "python_version": ["3.5.2"],
    "use_azure": "y",

    "_visual_studio": {
        "site_name": {
            "label": "Site name",
            "description": "E.g. <site-name>.azurewebsites.net (can only contain alphanumeric characters and `-`)"
        },
        "python_version": {
            "label": "Python version",
            "description": "The version of Python to run the site on"
        },
        "use_azure" : {
            "label": "Use Azure",
            "description": "Include Azure deployment files",
            "selector": "yesno",
            "url": "https://azure.microsoft.com"
        }
    }
}

Menjalankan tugas Visual Studio

Cookiecutter memiliki fitur yang disebut Post-Generate Hooks yang memungkinkan Anda menjalankan kode Python arbitrer setelah file dibuat. Meskipun fitur ini fleksibel, fitur ini tidak memungkinkan akses mudah ke Visual Studio.

Anda dapat menggunakan fitur ini untuk membuka file di editor Visual Studio atau browser webnya. Anda juga dapat memicu UI Visual Studio yang meminta pengguna untuk membuat lingkungan virtual dan menginstal persyaratan paket.

Untuk mengizinkan skenario ini, Visual Studio mencari metadata yang diperluas dalam file cookiecutter.json . Ini mencari perintah untuk dijalankan setelah pengguna membuka file yang dihasilkan di Penjelajah Solusi atau setelah file ditambahkan ke proyek yang ada. (Sekali lagi, pengguna dapat menolak menjalankan tugas dengan menghapus Jalankan tugas tambahan pada opsi templat penyelesaian .)

Contoh berikut menunjukkan cara mengatur metadata yang diperluas dalam file cookiecutter.json :

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": "{{cookiecutter._output_folder_path}}\\readme.txt"
    },
    {
        "name": "Cookiecutter.ExternalWebBrowser",
        "args": "https://learn.microsoft.com"
    },
    {
        "name": "Python.InstallProjectRequirements",
        "args": "{{cookiecutter._output_folder_path}}\\dev-requirements.txt"
    }
]

Tentukan perintah menurut nama dan gunakan nama nonlokalisasi (bahasa Inggris) untuk mengerjakan penginstalan Visual Studio yang dilokalkan. Anda dapat menguji dan menemukan nama perintah di jendela Perintah Visual Studio.

Jika Anda ingin meneruskan satu argumen, tentukan argumen sebagai string seperti yang ditunjukkan untuk name metadata dalam contoh sebelumnya.

Jika Anda tidak perlu meneruskan argumen, biarkan nilai sebagai string kosong atau hilangkan dari file JSON:

"_visual_studio_post_cmds": [
    {
        "name": "View.WebBrowser"
    }
]

Untuk beberapa argumen, gunakan array. Untuk sakelar, pisahkan sakelar dan nilainya menjadi argumen terpisah dan gunakan kutipan yang tepat, seperti yang ditunjukkan dalam contoh ini:

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": [
            "{{cookiecutter._output_folder_path}}\\read me.txt",
            "/e:",
            "Source Code (text) Editor"
        ]
    }
]

Argumen dapat merujuk ke variabel Cookiecutter lainnya. Dalam contoh sebelumnya, variabel internal _output_folder_path digunakan untuk membentuk jalur absolut untuk menghasilkan file.

Perintah Python.InstallProjectRequirements hanya berfungsi saat menambahkan file ke proyek yang ada. Batasan ini ada karena perintah diproses oleh proyek Python di Penjelajah Solusi, dan tidak ada proyek untuk menerima pesan saat berada dalam Tampilan Folder - Penjelajah Solusi.

Memecahkan masalah templat

Tinjau bagian berikut untuk tips tentang pemecahan masalah lingkungan dan kode Python Anda saat bekerja dengan Cookiecutter.

Kesalahan saat memuat templat

Beberapa templat mungkin menggunakan tipe data yang tidak valid dalam file cookiecutter.json mereka, seperti boolean. Anda dapat melaporkan instans ini ke pembuat templat dengan memilih tautan Masalah di panel informasi templat.

Skrip hook gagal

Beberapa templat mungkin menggunakan skrip pasca-generasi yang tidak kompatibel dengan UI Cookiecutter. Misalnya, skrip yang mengkueri pengguna untuk input dapat gagal karena kurangnya konsol terminal.

Skrip hook tidak didukung di Windows

Jika file skrip postingan .sh, file tersebut mungkin tidak terkait dengan aplikasi di komputer Windows Anda. Anda mungkin melihat permintaan dialog Windows untuk menemukan aplikasi yang kompatibel di penyimpanan Windows.

Templat dengan masalah yang diketahui

Anda dapat mengetahui apakah templat memiliki masalah yang diketahui dengan menggunakan tautan Masalah dalam ringkasan templat di Cookiecutter Explorer:

Tautan membuka halaman masalah GitHub untuk templat:

Konten terkait

• Referensi templat item Python
• Cookiecutter: Templat Proyek yang Lebih Baik