ASP.NET Core ile Angular proje şablonunu kullanma

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Visual Studio, ASP.NET Core arka ucuna sahip Angular, React ve Vue gibi JavaScript çerçevelerini temel alan tek sayfalı uygulamalar (SPA) oluşturmak için proje şablonları sağlar. Bu şablonlar:

  • Ön uç projesi ve arka uç projesiyle visual studio çözümü oluşturun.
  • Ön uç için JavaScript ve TypeScript (.esproj) için Visual Studio proje türünü kullanın.
  • Arka uç için bir ASP.NET Core projesi kullanın.

Visual Studio şablonları kullanılarak oluşturulan projeler Windows, Linux ve macOS'ta komut satırından çalıştırılabilir. Uygulamayı çalıştırmak için komutunu kullanarak dotnet run --launch-profile https sunucu projesini çalıştırın. Sunucu projesini çalıştırmak, ön uç JavaScript geliştirme sunucusunu otomatik olarak başlatır. Başlatma https profili şu anda gereklidir.

Visual Studio öğreticisi

Angular projesiyle çalışmaya başlamak için Visual Studio belgelerindeki Angular ile ASP.NET Core uygulaması oluşturma öğreticisini izleyin.

Daha fazla bilgi için bkz. Visual Studio'da JavaScript ve TypeScript

ASP.NET Core SPA şablonları

Visual Studio, JavaScript veya TypeScript ön ucuyla ASP.NET Core uygulamaları oluşturmaya yönelik şablonlar içerir. Bu şablonlar Visual Studio 2022 sürüm 17.8 veya sonraki sürümlerde ASP.NET ve web geliştirme iş yükü yüklü olarak kullanılabilir.

JavaScript veya TypeScript ön ucuyla ASP.NET Core uygulamaları oluşturmaya yönelik Visual Studio şablonları aşağıdaki avantajları sunar:

  • Ön uç ve arka uç için temiz proje ayrımı.
  • En son ön uç çerçevesi sürümleriyle güncel kalın.
  • Vite gibi en son ön uç çerçevesi komut satırı araçlarıyla tümleştirin.
  • Hem JavaScript hem de TypeScript için şablonlar (yalnızca Angular için TypeScript).
  • Zengin JavaScript ve TypeScript kod düzenleme deneyimi.
  • JavaScript derleme araçlarını .NET derlemesiyle tümleştirin.
  • npm bağımlılık yönetimi kullanıcı arabirimi.
  • Visual Studio Code hata ayıklama ve başlatma yapılandırmasıyla uyumludur.
  • JavaScript test çerçevelerini kullanarak Test Gezgini'nde ön uç birim testleri çalıştırın.

Eski ASP.NET Core SPA şablonları

.NET SDK'sının önceki sürümleri, ASP.NET Core ile SPA uygulamaları oluşturmaya yönelik eski şablonları içeriyor. Bu eski şablonlarla ilgili belgeler için SPA'ya genel bakış ASP.NET Core 7.0 sürümüne ve Angular ve React makalelerine bakın.

Angular ile ASP.NET Core proje şablonu, Angular ve Angular CLI kullanan ASP.NET Core uygulamalarının zengin, istemci tarafı kullanıcı arabirimi (UI) uygulaması için kullanışlı bir başlangıç noktası sağlar.

Proje şablonu hem web API'si olarak davranacak bir ASP.NET Core projesi hem de kullanıcı arabirimi olarak davranacak bir Angular CLI projesi oluşturmakla eşdeğerdir. Bu proje bileşimi, her iki projeyi de tek bir birim olarak oluşturulabilen ve yayımlanabilen tek bir ASP.NET Core projesinde barındırma kolaylığı sunar.

Proje şablonu sunucu tarafı işleme (SSR) için tasarlanmamıştır.

Yeni uygulama oluşturma

Komutunu boş bir dizinde kullanarak dotnet new angular komut isteminden yeni bir proje oluşturun. Örneğin, aşağıdaki komutlar uygulamayı bir my-new-app dizinde oluşturur ve bu dizine geçer:

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

Uygulamayı Visual Studio'dan veya .NET Core CLI'dan çalıştırın:

Oluşturulan .csproj dosyayı açın ve uygulamayı oradan normal şekilde çalıştırın.

Derleme işlemi ilk çalıştırmada npm bağımlılıklarını geri yükler ve bu işlem birkaç dakika sürebilir. Sonraki derlemeler çok daha hızlıdır.

Proje şablonu bir ASP.NET Core uygulaması ve angular uygulaması oluşturur. ASP.NET Core uygulamasının veri erişimi, yetkilendirme ve diğer sunucu tarafı endişeleri için kullanılması amaçlanmıştır. Alt dizinde bulunan Angular uygulamasının ClientApp tüm kullanıcı arabirimi endişeleri için kullanılması amaçlanmıştır.

Sayfa, resim, stil ve modül ekleme

Dizin, ClientApp standart bir Angular CLI uygulaması içerir. Daha fazla bilgi için resmi Angular belgelerine bakın.

Bu şablon tarafından oluşturulan Angular uygulaması ile Angular CLI tarafından oluşturulan uygulama arasında küçük farklılıklar vardır (aracılığıyla ng new); ancak uygulamanın özellikleri değişmez. Şablon tarafından oluşturulan uygulama, Bootstrap tabanlı bir düzen ve temel yönlendirme örneği içerir.

ng komutlarını çalıştırma

Komut isteminde alt dizine ClientApp geçin:

cd ClientApp

Aracı genel olarak yüklediyseniz ng komutlarından herhangi birini çalıştırabilirsiniz. Örneğin, , veya diğer Angular CLI komutlarından herhangi birini çalıştırabilirsinizng lint. ng test Ancak, ASP.NET Core uygulamanız uygulamanızın hem sunucu tarafı hem de istemci tarafı bölümlerine hizmet vermekle çalıştığından çalıştırmanız ng serve gerekmez. Dahili olarak geliştirme aşamasında kullanılır ng serve .

ng Araç yüklü değilse, bunun yerine komutunu çalıştırınnpm run ng. Örneğin, veya npm run ng testkomutunu çalıştırabilirsiniznpm run ng lint.

npm paketlerini yükleme

Üçüncü taraf npm paketlerini yüklemek için alt dizinde ClientApp bir komut istemi kullanın. Örneğin:

cd ClientApp
npm install <package_name>

Yayımlama ve dağıtma

Geliştirme aşamasında uygulama, geliştirici kolaylığı için iyileştirilmiş bir modda çalışır. Örneğin, JavaScript paketleri kaynak eşlemeleri içerir (böylece hata ayıklarken özgün TypeScript kodunuzu görebilirsiniz). Uygulama, diskte TypeScript, HTML ve CSS dosyası değişikliklerini izler ve bu dosyaların değiştiğini gördüğünde otomatik olarak yeniden derlenir ve yeniden yüklenir.

Üretimde, uygulamanızın performans için iyileştirilmiş bir sürümünü sunun. Bu, otomatik olarak gerçekleşecek şekilde yapılandırılır. Yayımladığınızda, derleme yapılandırması istemci tarafı kodunuzun küçültülmüş, önceden derlenmiş bir derlemesini (AoT) yayar. Geliştirme derlemesinin aksine, üretim derlemesi sunucuda Node.js yüklenmesini gerektirmez (sunucu tarafı işlemeyi (SSR) etkinleştirmediğiniz sürece).

Standart ASP.NET Core barındırma ve dağıtım yöntemlerini kullanabilirsiniz.

"ng serve" komutunu bağımsız olarak çalıştırma

proje, ASP.NET Core uygulaması geliştirme modunda başladığında arka planda angular CLI sunucusunun kendi örneğini başlatacak şekilde yapılandırılır. Ayrı bir sunucuyu el ile çalıştırmanız gerekmeyen bu kullanışlı bir işlemdir.

Bu varsayılan kurulumun bir dezavantajı vardır. C# kodunuzu değiştirdiğinizde ve ASP.NET Core uygulamanızın yeniden başlatılması gerektiğinde Angular CLI sunucusu yeniden başlatılır. Yedeklemeyi başlatmak için yaklaşık 10 saniye gerekir. Sık sık C# kodu düzenlemeleri yapıyorsanız ve Angular CLI'nin yeniden başlatılmasını beklemek istemiyorsanız Angular CLI sunucusunu ASP.NET Core işleminden bağımsız olarak harici olarak çalıştırın.

Angular CLI sunucusunu harici olarak çalıştırmak için komut isteminde alt dizine ClientApp geçin ve Angular CLI geliştirme sunucusunu başlatın:

cd ClientApp
npm start

ASP.NET Core uygulamanızı başlattığınızda angular CLI sunucusu başlatılmaz. Bunun yerine el ile başlattığınız örnek kullanılır. Bu, daha hızlı başlatılmasını ve yeniden başlatılmasını sağlar. Artık Angular CLI'nin istemci uygulamanızı her seferinde yeniden oluşturmasını beklemiyorum.

Ara sunucu başlatıldığında, hedef URL ve bağlantı noktası .NET ASPNETCORE_URLSASPNETCORE_HTTPS_PORTSve tarafından ayarlanan ortam değişkenlerinden çıkarılır. URL'leri veya HTTPS bağlantı noktasını ayarlamak için ortam değişkenlerinden birini kullanın veya içindeki proxy.conf.jsondeğeri değiştirin.

Için ara sunucu ara yazılımını yapılandırma SignalR

Daha fazla bilgi için bkz . http-proxy-ara yazılım.

Ek kaynaklar

Güncelleştirilmiş Angular proje şablonu, zengin, istemci tarafı kullanıcı arabirimi (UI) uygulamak için Angular ve Angular CLI kullanan ASP.NET Core uygulamaları için kullanışlı bir başlangıç noktası sağlar.

Şablon, API arka ucu olarak hareket eden bir ASP.NET Core projesi ve kullanıcı arabirimi işlevi görmek için Angular CLI projesi oluşturmaya eşdeğerdir. Şablon, her iki proje türünü de tek bir uygulama projesinde barındırma kolaylığı sunar. Sonuç olarak, uygulama projesi tek bir birim olarak derlenebilir ve yayımlanabilir.

Yeni uygulama oluşturma

Komutunu boş bir dizinde kullanarak dotnet new angular komut isteminden yeni bir proje oluşturun. Örneğin, aşağıdaki komutlar uygulamayı bir my-new-app dizinde oluşturur ve bu dizine geçer:

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

Uygulamayı Visual Studio'dan veya .NET Core CLI'dan çalıştırın:

Oluşturulan .csproj dosyayı açın ve uygulamayı oradan normal şekilde çalıştırın.

Derleme işlemi ilk çalıştırmada npm bağımlılıklarını geri yükler ve bu işlem birkaç dakika sürebilir. Sonraki derlemeler çok daha hızlıdır.

Proje şablonu bir ASP.NET Core uygulaması ve angular uygulaması oluşturur. ASP.NET Core uygulamasının veri erişimi, yetkilendirme ve diğer sunucu tarafı endişeleri için kullanılması amaçlanmıştır. Alt dizinde bulunan Angular uygulamasının ClientApp tüm kullanıcı arabirimi endişeleri için kullanılması amaçlanmıştır.

Sayfa, resim, stil ve modül ekleme

Dizin, ClientApp standart bir Angular CLI uygulaması içerir. Daha fazla bilgi için resmi Angular belgelerine bakın.

Bu şablon tarafından oluşturulan Angular uygulaması ile Angular CLI tarafından oluşturulan uygulama arasında küçük farklılıklar vardır (aracılığıyla ng new); ancak uygulamanın özellikleri değişmez. Şablon tarafından oluşturulan uygulama, Bootstrap tabanlı bir düzen ve temel yönlendirme örneği içerir.

ng komutlarını çalıştırma

Komut isteminde alt dizine ClientApp geçin:

cd ClientApp

Aracı genel olarak yüklediyseniz ng komutlarından herhangi birini çalıştırabilirsiniz. Örneğin, , veya diğer Angular CLI komutlarından herhangi birini çalıştırabilirsinizng lint. ng test Ancak, ASP.NET Core uygulamanız uygulamanızın hem sunucu tarafı hem de istemci tarafı bölümlerine hizmet vermekle çalıştığından çalıştırmanız ng serve gerekmez. Dahili olarak geliştirme aşamasında kullanılır ng serve .

ng Araç yüklü değilse, bunun yerine komutunu çalıştırınnpm run ng. Örneğin, veya npm run ng testkomutunu çalıştırabilirsiniznpm run ng lint.

npm paketlerini yükleme

Üçüncü taraf npm paketlerini yüklemek için alt dizinde ClientApp bir komut istemi kullanın. Örneğin:

cd ClientApp
npm install --save <package_name>

Yayımlama ve dağıtma

Geliştirme aşamasında uygulama, geliştirici kolaylığı için iyileştirilmiş bir modda çalışır. Örneğin, JavaScript paketleri kaynak eşlemeleri içerir (böylece hata ayıklarken özgün TypeScript kodunuzu görebilirsiniz). Uygulama, diskte TypeScript, HTML ve CSS dosyası değişikliklerini izler ve bu dosyaların değiştiğini gördüğünde otomatik olarak yeniden derlenir ve yeniden yüklenir.

Üretimde, uygulamanızın performans için iyileştirilmiş bir sürümünü sunun. Bu, otomatik olarak gerçekleşecek şekilde yapılandırılır. Yayımladığınızda, derleme yapılandırması istemci tarafı kodunuzun küçültülmüş, önceden derlenmiş bir derlemesini (AoT) yayar. Geliştirme derlemesinin aksine, üretim derlemesi sunucuda Node.js yüklenmesini gerektirmez (sunucu tarafı işlemeyi (SSR) etkinleştirmediğiniz sürece).

Standart ASP.NET Core barındırma ve dağıtım yöntemlerini kullanabilirsiniz.

"ng serve" komutunu bağımsız olarak çalıştırma

proje, ASP.NET Core uygulaması geliştirme modunda başladığında arka planda angular CLI sunucusunun kendi örneğini başlatacak şekilde yapılandırılır. Ayrı bir sunucuyu el ile çalıştırmanız gerekmeyen bu kullanışlı bir işlemdir.

Bu varsayılan kurulumun bir dezavantajı vardır. C# kodunuzu değiştirdiğinizde ve ASP.NET Core uygulamanızın yeniden başlatılması gerektiğinde Angular CLI sunucusu yeniden başlatılır. Yedeklemeyi başlatmak için yaklaşık 10 saniye gerekir. Sık sık C# kodu düzenlemeleri yapıyorsanız ve Angular CLI'nin yeniden başlatılmasını beklemek istemiyorsanız Angular CLI sunucusunu ASP.NET Core işleminden bağımsız olarak harici olarak çalıştırın. Yapmak için:

  1. Komut isteminde alt dizine ClientApp geçin ve Angular CLI geliştirme sunucusunu başlatın:

    cd ClientApp
npm start

    Önemli

    içindeki yapılandırmaya package.json uyulması için yerine Angular CLI geliştirme sunucusunu ng servebaşlatmak için kullanınnpm start. Angular CLI sunucusuna ek parametreler geçirmek için bunları dosyanızdaki package.json ilgili scripts satıra ekleyin.

  2. ASP.NET Core uygulamanızı kendi uygulamanızı başlatmak yerine dış Angular CLI örneğini kullanacak şekilde değiştirin. Başlangıç sınıfınızda çağrıyı spa.UseAngularCliServer aşağıdakilerle değiştirin:

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

ASP.NET Core uygulamanızı başlattığınızda angular CLI sunucusu başlatılmaz. Bunun yerine el ile başlattığınız örnek kullanılır. Bu, daha hızlı başlatılmasını ve yeniden başlatılmasını sağlar. Artık Angular CLI'nin istemci uygulamanızı her seferinde yeniden oluşturmasını beklemiyorum.

Ara sunucu başlatıldığında, hedef URL ve bağlantı noktası .NET ASPNETCORE_URLSASPNETCORE_HTTPS_PORTSve tarafından ayarlanan ortam değişkenlerinden çıkarılır. URL'leri veya HTTPS bağlantı noktasını ayarlamak için ortam değişkenlerinden birini kullanın veya içindeki proxy.conf.jsondeğeri değiştirin.

.NET kodundan TypeScript koduna veri geçirme

SSR sırasında, ASP.NET Core uygulamanızdaki istek başına verileri Angular uygulamanıza geçirmek isteyebilirsiniz. Örneğin, veritabanından bilgi veya okunmuş bir şey geçirebilirsiniz cookie . Bunu yapmak için Başlangıç sınıfınızı düzenleyin. için UseSpaPrerenderinggeri çağırmada için options.SupplyData aşağıdaki gibi bir değer ayarlayın:

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

SupplyData Geri arama rastgele, istek başına, JSON serileştirilebilir verileri (örneğin, dizeler, boole'lar veya sayılar) geçirmenizi sağlar. Kodunuz main.server.ts bunu olarak params.dataalır. Örneğin, önceki kod örneği geri çağırmaya createServerRenderer boole değeri olarak params.data.isHttpsRequest geçirir. Bunu, Angular tarafından desteklenen herhangi bir şekilde uygulamanızın diğer bölümlerine geçirebilirsiniz. Örneğin, değerini, oluşturucusunun BASE_URL almak üzere bildirdiği herhangi bir bileşene nasıl main.server.ts geçirdiğine bakın.

SSR'nin Dezavantajları

Tüm uygulamalar SSR'den yararlanmıyor. Birincil avantaj, algılanan performanstır. Uygulamanıza yavaş bir ağ bağlantısı üzerinden veya yavaş mobil cihazlardan ulaşan ziyaretçiler, JavaScript paketlerini getirmek veya ayrıştırmak biraz zaman alsa bile ilk kullanıcı arabirimini hızlı bir şekilde görür. Ancak, çoğu SPA genellikle uygulamanın neredeyse anında göründüğü hızlı bilgisayarlarda hızlı, iç şirket ağları üzerinden kullanılır.

Aynı zamanda SSR'yi etkinleştirmenin önemli dezavantajları da vardır. Geliştirme sürecinize karmaşıklık ekler. Kodunuzun iki farklı ortamda çalışması gerekir: istemci tarafı ve sunucu tarafı (ASP.NET Core'dan çağrılan Node.js bir ortamda). Aklınızda bulundurması gereken bazı şeyler şunlardır:

  • SSR, üretim sunucularınıza Node.js bir yükleme gerektirir. Bu, Azure Uygulaması Hizmetleri gibi bazı dağıtım senaryolarında otomatik olarak geçerlidir ancak Azure Service Fabric gibi diğerleri için geçerli değildir.
  • Derleme bayrağını BuildServerSideRenderer etkinleştirmek, node_modules dizininizin yayımlamasına neden olur. Bu klasör, dağıtım süresini artıran 20.000'den fazla dosya içerir.
  • Kodunuzu Node.js bir ortamda çalıştırmak için veya localStoragegibi window tarayıcıya özgü JavaScript API'lerinin varlığına dayanamaz. Kodunuz (veya başvurabileceğiniz bazı üçüncü taraf kitaplıkları) bu API'leri kullanmayı denerse, SSR sırasında bir hata alırsınız. Örneğin, birçok yerde tarayıcıya özgü API'lere başvuracağından jQuery kullanmayın. Hataları önlemek için SSR'yi veya tarayıcıya özgü API'leri veya kitaplıkları önlemeniz gerekir. Bu tür API'lere yapılan çağrıları, SSR sırasında çağrılmadığından emin olmak için denetimlerde sarmalayabilirsiniz. Örneğin, JavaScript veya TypeScript kodunda aşağıdaki gibi bir denetim kullanın:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Için ara sunucu ara yazılımını yapılandırma SignalR

Daha fazla bilgi için bkz . http-proxy-ara yazılım.

Ek kaynaklar