Bagikan melalui

Menggunakan templat proyek Angular dengan ASP.NET Core

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Visual Studio menyediakan templat proyek untuk membuat aplikasi satu halaman (SPAs) berdasarkan kerangka kerja JavaScript seperti Angular, React, dan Vue yang memiliki backend ASP.NET Core. Templat ini:

  • Buat solusi Visual Studio dengan proyek frontend dan proyek backend.
  • Gunakan jenis proyek Visual Studio untuk JavaScript dan TypeScript (.esproj) untuk frontend.
  • Gunakan proyek ASP.NET Core untuk backend.

Proyek yang dibuat dengan menggunakan templat Visual Studio dapat dijalankan dari baris perintah di Windows, Linux, dan macOS. Untuk menjalankan aplikasi, gunakan dotnet run --launch-profile https untuk menjalankan proyek server. Menjalankan proyek server secara otomatis memulai server pengembangan JavaScript frontend. Profil https peluncuran saat ini diperlukan.

Tutorial Visual Studio

Untuk mulai menggunakan proyek Angular, ikuti tutorial Membuat aplikasi ASP.NET Core dengan Angular dalam dokumentasi Visual Studio.

Untuk informasi selengkapnya, lihat JavaScript dan TypeScript di Visual Studio

ASP.NET templat SPA Inti

Visual Studio menyertakan templat untuk membangun aplikasi ASP.NET Core dengan frontend JavaScript atau TypeScript. Templat ini tersedia di Visual Studio 2022 versi 17.8 atau yang lebih baru dengan beban kerja ASP.NET dan pengembangan web terinstal.

Templat Visual Studio untuk membangun aplikasi ASP.NET Core dengan frontend JavaScript atau TypeScript menawarkan manfaat berikut:

  • Bersihkan pemisahan proyek untuk frontend dan backend.
  • Tetap up-to-date dengan versi kerangka kerja frontend terbaru.
  • Integrasikan dengan alat baris perintah kerangka kerja frontend terbaru, seperti Vite.
  • Templat untuk JavaScript & TypeScript (hanya TypeScript untuk Angular).
  • Pengalaman pengeditan kode JavaScript dan TypeScript yang kaya.
  • Integrasikan alat build JavaScript dengan build .NET.
  • UI manajemen dependensi npm.
  • Kompatibel dengan debugging Visual Studio Code dan konfigurasi peluncuran.
  • Jalankan pengujian unit frontend di Test Explorer menggunakan kerangka kerja pengujian JavaScript.

Templat Warisan ASP.NET Core SPA

Versi .NET SDK yang lebih lama menyertakan templat warisan apa yang sekarang untuk membangun aplikasi SPA dengan ASP.NET Core. Untuk dokumentasi tentang templat lama ini, lihat gambaran umum SPA versi ASP.NET Core 7.0 dan artikel Angular dan React .

Templat proyek ASP.NET Core with Angular menyediakan titik awal yang nyaman untuk aplikasi ASP.NET Core menggunakan Angular dan CLI Angular untuk mengimplementasikan antarmuka pengguna (UI) sisi klien yang kaya.

Templat proyek setara dengan membuat proyek ASP.NET Core untuk bertindak sebagai API web dan proyek Angular CLI untuk bertindak sebagai UI. Kombinasi proyek ini menawarkan kenyamanan menghosting kedua proyek dalam satu proyek ASP.NET Core yang dapat dibangun dan diterbitkan sebagai satu unit.

Templat proyek tidak dimaksudkan untuk penyajian sisi server (SSR).

Membuat aplikasi baru

Buat proyek baru dari prompt perintah menggunakan perintah dotnet new angular di direktori kosong. Misalnya, perintah berikut membuat aplikasi di my-new-app direktori dan beralih ke direktori tersebut:

dotnet new angular -o my-new-app
cd my-new-app

Jalankan aplikasi dari Visual Studio atau .NET CLI:

Buka file yang dihasilkan .csproj , dan jalankan aplikasi seperti biasa dari sana.

Proses build memulihkan dependensi npm pada eksekusi pertama, yang dapat memakan waktu beberapa menit. Build berikutnya jauh lebih cepat.

Templat proyek membuat aplikasi ASP.NET Core dan aplikasi Angular. Aplikasi ASP.NET Core dimaksudkan untuk digunakan untuk akses data, otorisasi, dan masalah sisi server lainnya. Aplikasi Angular, yang berada di ClientApp subdirektori, dimaksudkan untuk digunakan untuk semua masalah UI.

Menambahkan halaman, gambar, gaya, dan modul

ClientApp Direktori berisi aplikasi CLI Angular standar. Lihat dokumentasi resmi Angular untuk informasi selengkapnya.

Ada sedikit perbedaan antara aplikasi Angular yang dibuat oleh templat ini dan yang dibuat oleh Angular CLI itu sendiri (melalui ng new); namun, kemampuan aplikasi tidak berubah. Aplikasi yang dibuat oleh templat berisi tata letak berbasis Bootstrap dan contoh perutean dasar.

Menjalankan perintah ng

Di prompt perintah, beralihlah ke subdirektori ClientApp :

cd ClientApp

Jika Anda memiliki alat yang ng diinstal secara global, Anda dapat menjalankan salah satu perintahnya. Misalnya, Anda dapat menjalankan ng lint, ng test, atau perintah CLI Angular lainnya. Namun, tidak perlu dijalankan ng serve karena aplikasi ASP.NET Core Anda menangani penyajian bagian sisi server dan sisi klien aplikasi Anda. Secara internal, ia menggunakan ng serve dalam pengembangan.

Jika Anda tidak menginstal alat, jalankan npm run ng sebagai gantinyang. Misalnya, Anda dapat menjalankan npm run ng lint atau npm run ng test.

Memasang paket npm

Untuk menginstal paket npm pihak ketiga, gunakan prompt perintah di subdirektori ClientApp . Contohnya:

cd ClientApp
npm install <package_name>

Menerbitkan dan menyebarkan

Dalam pengembangan, aplikasi berjalan dalam mode yang dioptimalkan untuk kenyamanan pengembang. Misalnya, bundel JavaScript menyertakan peta sumber (sehingga saat penelusuran kesalahan, Anda dapat melihat kode TypeScript asli Anda). Aplikasi mengawasi perubahan file TypeScript, HTML, dan CSS pada disk dan secara otomatis mengkombinasi ulang dan memuat ulang ketika melihat file tersebut berubah.

Dalam produksi, sajikan versi aplikasi Anda yang dioptimalkan untuk performa. Ini dikonfigurasi untuk terjadi secara otomatis. Saat Anda menerbitkan, konfigurasi build memancarkan build yang dikurangi dan dikompilasi sebelumnya (AoT) dari kode sisi klien Anda. Tidak seperti build pengembangan, build produksi tidak mengharuskan Node.js diinstal di server (kecuali Anda telah mengaktifkan penyajian sisi server (SSR)).

Anda dapat menggunakan metode hosting dan penyebaran ASP.NET Core standar.

Jalankan "ng serve" secara independen

Proyek ini dikonfigurasi untuk memulai instans server CLI Angular sendiri di latar belakang saat aplikasi ASP.NET Core dimulai dalam mode pengembangan. Ini nyaman karena Anda tidak perlu menjalankan server terpisah secara manual.

Ada kelemahan untuk penyiapan default ini. Setiap kali Anda memodifikasi kode C# dan aplikasi ASP.NET Core Anda perlu dimulai ulang, server CLI Angular dimulai ulang. Sekitar 10 detik diperlukan untuk memulai pencadangan. Jika Anda sering melakukan pengeditan kode C# dan tidak ingin menunggu CLI Angular dimulai ulang, jalankan server CLI Angular secara eksternal, secara independen dari proses ASP.NET Core.

Untuk menjalankan server CLI Angular secara eksternal, beralihlah ke ClientApp subdirektori dalam prompt perintah dan luncurkan server pengembangan Angular CLI:

cd ClientApp
npm start

Saat Anda memulai aplikasi ASP.NET Core, aplikasi tersebut tidak akan meluncurkan server Angular CLI. Instans yang Anda mulai secara manual digunakan sebagai gantinya. Ini memungkinkannya untuk memulai dan memulai ulang lebih cepat. Tidak lagi menunggu CLI Angular membangun kembali aplikasi klien Anda setiap kali.

Ketika proksi diluncurkan, URL target dan port disimpulkan dari variabel lingkungan yang ditetapkan oleh .NET, ASPNETCORE_URLS dan ASPNETCORE_HTTPS_PORTS. Untuk mengatur URL atau port HTTPS, gunakan salah satu variabel lingkungan atau ubah nilai di proxy.conf.json.

Mengonfigurasi middleware proksi untuk SignalR

Untuk informasi selengkapnya, lihat http-proxy-middleware.

Sumber Daya Tambahan:

Templat proyek Angular yang diperbarui menyediakan titik awal yang nyaman untuk aplikasi ASP.NET Core menggunakan Angular dan CLI Angular untuk mengimplementasikan antarmuka pengguna (UI) sisi klien yang kaya.

Templat ini setara dengan membuat proyek ASP.NET Core untuk bertindak sebagai backend API dan proyek CLI Angular untuk bertindak sebagai UI. Templat ini menawarkan kenyamanan menghosting kedua jenis proyek dalam satu proyek aplikasi. Akibatnya, proyek aplikasi dapat dibangun dan diterbitkan sebagai satu unit.

Membuat aplikasi baru

Buat proyek baru dari prompt perintah menggunakan perintah dotnet new angular di direktori kosong. Misalnya, perintah berikut membuat aplikasi di my-new-app direktori dan beralih ke direktori tersebut:

dotnet new angular -o my-new-app
cd my-new-app

Jalankan aplikasi dari Visual Studio atau .NET CLI:

Buka file yang dihasilkan .csproj , dan jalankan aplikasi seperti biasa dari sana.

Proses build memulihkan dependensi npm pada eksekusi pertama, yang dapat memakan waktu beberapa menit. Build berikutnya jauh lebih cepat.

Templat proyek membuat aplikasi ASP.NET Core dan aplikasi Angular. Aplikasi ASP.NET Core dimaksudkan untuk digunakan untuk akses data, otorisasi, dan masalah sisi server lainnya. Aplikasi Angular, yang berada di ClientApp subdirektori, dimaksudkan untuk digunakan untuk semua masalah UI.

Menambahkan halaman, gambar, gaya, dan modul

ClientApp Direktori berisi aplikasi CLI Angular standar. Lihat dokumentasi resmi Angular untuk informasi selengkapnya.

Ada sedikit perbedaan antara aplikasi Angular yang dibuat oleh templat ini dan yang dibuat oleh Angular CLI itu sendiri (melalui ng new); namun, kemampuan aplikasi tidak berubah. Aplikasi yang dibuat oleh templat berisi tata letak berbasis Bootstrap dan contoh perutean dasar.

Menjalankan perintah ng

Di prompt perintah, beralihlah ke subdirektori ClientApp :

cd ClientApp

Jika Anda memiliki alat yang ng diinstal secara global, Anda dapat menjalankan salah satu perintahnya. Misalnya, Anda dapat menjalankan ng lint, ng test, atau perintah CLI Angular lainnya. Namun, tidak perlu dijalankan ng serve karena aplikasi ASP.NET Core Anda menangani penyajian bagian sisi server dan sisi klien aplikasi Anda. Secara internal, ia menggunakan ng serve dalam pengembangan.

Jika Anda tidak menginstal alat, jalankan npm run ng sebagai gantinyang. Misalnya, Anda dapat menjalankan npm run ng lint atau npm run ng test.

Memasang paket npm

Untuk menginstal paket npm pihak ketiga, gunakan prompt perintah di subdirektori ClientApp . Contohnya:

cd ClientApp
npm install --save <package_name>

Menerbitkan dan menyebarkan

Dalam pengembangan, aplikasi berjalan dalam mode yang dioptimalkan untuk kenyamanan pengembang. Misalnya, bundel JavaScript menyertakan peta sumber (sehingga saat penelusuran kesalahan, Anda dapat melihat kode TypeScript asli Anda). Aplikasi mengawasi perubahan file TypeScript, HTML, dan CSS pada disk dan secara otomatis mengkombinasi ulang dan memuat ulang ketika melihat file tersebut berubah.

Dalam produksi, sajikan versi aplikasi Anda yang dioptimalkan untuk performa. Ini dikonfigurasi untuk terjadi secara otomatis. Saat Anda menerbitkan, konfigurasi build memancarkan build yang dikurangi dan dikompilasi sebelumnya (AoT) dari kode sisi klien Anda. Tidak seperti build pengembangan, build produksi tidak mengharuskan Node.js diinstal di server (kecuali Anda telah mengaktifkan penyajian sisi server (SSR)).

Anda dapat menggunakan metode hosting dan penyebaran ASP.NET Core standar.

Jalankan "ng serve" secara independen

Proyek ini dikonfigurasi untuk memulai instans server CLI Angular sendiri di latar belakang saat aplikasi ASP.NET Core dimulai dalam mode pengembangan. Ini nyaman karena Anda tidak perlu menjalankan server terpisah secara manual.

Ada kelemahan untuk penyiapan default ini. Setiap kali Anda memodifikasi kode C# dan aplikasi ASP.NET Core Anda perlu dimulai ulang, server CLI Angular dimulai ulang. Sekitar 10 detik diperlukan untuk memulai pencadangan. Jika Anda sering melakukan pengeditan kode C# dan tidak ingin menunggu CLI Angular dimulai ulang, jalankan server CLI Angular secara eksternal, secara independen dari proses ASP.NET Core. Untuk melakukannya:

  1. Dalam prompt perintah, beralihlah ke ClientApp subdirektori, dan luncurkan server pengembangan Angular CLI:

    cd ClientApp
npm start

    Penting

    Gunakan npm start untuk meluncurkan server pengembangan CLI Angular, bukan ng serve, sehingga konfigurasi dihormati package.json . Untuk meneruskan parameter tambahan ke server Angular CLI, tambahkan ke baris yang relevan scripts dalam file Anda package.json .

  2. Ubah aplikasi ASP.NET Core Anda untuk menggunakan instans CLI Angular eksternal alih-alih meluncurkan salah satu aplikasinya sendiri. Di kelas Startup Anda, ganti spa.UseAngularCliServer pemanggilan dengan yang berikut:

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");

Saat Anda memulai aplikasi ASP.NET Core, aplikasi tersebut tidak akan meluncurkan server Angular CLI. Instans yang Anda mulai secara manual digunakan sebagai gantinya. Ini memungkinkannya untuk memulai dan memulai ulang lebih cepat. Tidak lagi menunggu CLI Angular membangun kembali aplikasi klien Anda setiap kali.

Ketika proksi diluncurkan, URL target dan port disimpulkan dari variabel lingkungan yang ditetapkan oleh .NET, ASPNETCORE_URLS dan ASPNETCORE_HTTPS_PORTS. Untuk mengatur URL atau port HTTPS, gunakan salah satu variabel lingkungan atau ubah nilai di proxy.conf.json.

Meneruskan data dari kode .NET ke kode TypeScript

Selama SSR, Anda mungkin ingin meneruskan data per permintaan dari aplikasi ASP.NET Core ke aplikasi Angular Anda. Misalnya, Anda dapat meneruskan cookie informasi atau sesuatu yang dibaca dari database. Untuk melakukan ini, edit kelas Startup Anda. Dalam panggilan balik untuk UseSpaPrerendering, tetapkan nilai untuk options.SupplyData seperti berikut ini:

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

Panggilan SupplyData balik memungkinkan Anda meneruskan data yang dapat diserialisasikan, per permintaan, JSon-serializable (misalnya, string, boolean, atau angka). Kode Anda main.server.ts menerima ini sebagai params.data. Misalnya, sampel kode sebelumnya meneruskan nilai boolean seperti params.data.isHttpsRequest ke createServerRenderer dalam panggilan balik. Anda dapat meneruskan ini ke bagian lain aplikasi Anda dengan cara apa pun yang didukung oleh Angular. Misalnya, lihat bagaimana main.server.ts meneruskan BASE_URL nilai ke komponen mana pun yang konstruktornya dinyatakan menerimanya.

Kelemahan SSR

Tidak semua aplikasi mendapat manfaat dari SSR. Manfaat utama adalah performa yang dirasakan. Pengunjung yang menjangkau aplikasi Anda melalui koneksi jaringan yang lambat atau di perangkat seluler yang lambat melihat antarmuka pengguna awal dengan cepat, bahkan jika perlu waktu beberapa saat untuk mengambil atau mengurai bundel JavaScript. Namun, banyak SPA terutama digunakan melalui jaringan perusahaan internal yang cepat di komputer cepat di mana aplikasi muncul hampir seketika.

Pada saat yang sama, ada kelemahan yang signifikan untuk mengaktifkan SSR. Ini menambah kompleksitas pada proses pengembangan Anda. Kode Anda harus berjalan di dua lingkungan yang berbeda: sisi klien dan sisi server (di lingkungan Node.js yang dipanggil dari ASP.NET Core). Berikut adalah beberapa hal yang perlu diingat:

  • SSR memerlukan penginstalan Node.js di server produksi Anda. Ini secara otomatis terjadi untuk beberapa skenario penyebaran, seperti Azure App Services, tetapi tidak untuk yang lain, seperti Azure Service Fabric.
  • Mengaktifkan BuildServerSideRenderer bendera build menyebabkan direktori node_modules Anda diterbitkan. Folder ini berisi 20.000+ file, yang meningkatkan waktu penyebaran.
  • Untuk menjalankan kode Anda di lingkungan Node.js, kode tidak dapat mengandalkan keberadaan API JavaScript khusus browser seperti window atau localStorage. Jika kode Anda (atau beberapa pustaka pihak ketiga yang Anda referensikan) mencoba menggunakan API ini, Anda akan mendapatkan kesalahan selama SSR. Misalnya, jangan gunakan jQuery karena mereferensikan API khusus browser di banyak tempat. Untuk mencegah kesalahan, Anda harus menghindari SSR atau menghindari API atau pustaka khusus browser. Anda dapat membungkus panggilan apa pun ke API tersebut dalam pemeriksaan untuk memastikan mereka tidak dipanggil selama SSR. Misalnya, gunakan pemeriksaan seperti berikut ini dalam kode JavaScript atau TypeScript:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Mengonfigurasi middleware proksi untuk SignalR

Untuk informasi selengkapnya, lihat http-proxy-middleware.

Sumber Daya Tambahan: