.NET .NET Aspire ringkasan jaringan lingkaran dalam

Salah satu keuntungan mengembangkan dengan .NET.NET Aspire adalah memungkinkan Anda mengembangkan, menguji, dan men-debug aplikasi cloud-native secara lokal. Jaringan internal-loop adalah aspek utama .NET.NET Aspire yang memungkinkan aplikasi saling berkomunikasi dalam lingkungan pengembangan Anda. Dalam artikel ini, Anda mempelajari bagaimana .NET.NET Aspire menangani berbagai skenario jaringan dengan proksi, titik akhir, konfigurasi titik akhir, dan profil peluncuran.

Jaringan dalam siklus internal

Perulangan dalam adalah proses pengembangan dan pengujian aplikasi Anda secara lokal sebelum menyebarkannya ke lingkungan target. .NET .NET Aspire menyediakan beberapa alat dan fitur untuk menyederhanakan dan meningkatkan pengalaman jaringan dalam siklus internal, seperti:

• Luncurkan profil: Profil peluncuran adalah file konfigurasi yang menentukan cara menjalankan aplikasi Anda secara lokal. Anda dapat menggunakan profil peluncuran (seperti file launchSettings.json) untuk menentukan titik akhir, variabel lingkungan, dan pengaturan peluncuran untuk aplikasi Anda.
• konfigurasi Kestrel: Konfigurasi Kestrel memungkinkan Anda menentukan titik akhir yang didengarkan oleh server web Kestrel. Anda dapat mengonfigurasi titik akhir Kestrel di pengaturan aplikasi, dan .NET.NET Aspire secara otomatis menggunakan pengaturan ini untuk membuat titik akhir.
• Titik Akhir/Konfigurasi Titik Akhir: Titik akhir adalah koneksi antara aplikasi Anda dan layanan yang bergantung, seperti database, antrean pesan, atau API. Titik akhir menyediakan informasi seperti nama layanan, port host, skema, dan variabel lingkungan. Anda dapat menambahkan titik akhir ke aplikasi Anda baik secara implisit (melalui profil peluncuran) atau secara eksplisit dengan memanggil WithEndpoint.
• Proksi: .NET.NET Aspire secara otomatis meluncurkan proksi untuk setiap pembindahan layanan yang Anda tambahkan ke aplikasi milik Anda, dan menetapkan port untuk diakses oleh proksi. Proksi kemudian meneruskan permintaan ke port yang didengarkan aplikasi Anda, yang mungkin berbeda dari port proksi. Dengan cara ini, Anda dapat menghindari konflik port dan mengakses aplikasi dan layanan Anda menggunakan URL yang konsisten dan dapat diprediksi.

Cara kerja titik akhir

Pengikatan layanan di melibatkan dua integrasi: layanan mewakili sumber daya eksternal yang diperlukan aplikasi Anda (misalnya, database, antrean pesan, atau API), dan pengikatan yang membangun koneksi antara aplikasi Anda dan layanan dan memberikan informasi yang diperlukan.

.NET .NET Aspire mendukung dua jenis pengikatan layanan: implisit , dibuat secara otomatis berdasarkan profil peluncuran yang ditentukan yang menentukan perilaku aplikasi di lingkungan yang berbeda, dan eksplisit , dibuat secara manual menggunakan WithEndpoint.

Setelah membuat pengikatan, baik implisit atau eksplisit, .NET.NET Aspire meluncurkan proksi terbalik ringan pada port tertentu, menangani perutean dan penyeimbangan beban untuk permintaan dari aplikasi Anda ke layanan. Proksi adalah detail implementasi .NET.NET Aspire, tidak memerlukan masalah konfigurasi atau manajemen.

Untuk membantu memvisualisasikan cara kerja titik akhir, pertimbangkan diagram jaringan lingkaran dalam pada templat pemula .NET.NET Aspire.

Luncurkan profil

Saat Anda memanggil AddProject, host aplikasi mencari Properties/launchSettings.json untuk menentukan kumpulan titik akhir default. Host aplikasi memilih profil peluncuran tertentu menggunakan aturan berikut:

1. Argumen launchProfileName eksplisit diteruskan saat memanggil AddProject.
2. Variabel lingkungan DOTNET_LAUNCH_PROFILE. Untuk informasi selengkapnya, lihat variabel lingkungan .NET.
3. Profil peluncuran pertama yang ditentukan dalam launchSettings.json.

Pertimbangkan file launchSettings.json berikut:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "applicationUrl": "https://localhost:7239;http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Untuk sisa artikel ini, bayangkan Anda telah membuat IDistributedApplicationBuilder yang ditetapkan ke variabel bernama builder dengan API CreateBuilder():

var builder = DistributedApplication.CreateBuilder(args);

Untuk menentukan http dan profil peluncuran https , konfigurasikan nilai untuk keduanya dalam file launchSettings.json. URL ini digunakan untuk membuat titik akhir untuk proyek ini. Ini setara dengan:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithHttpsEndpoint(port: 7239);

Untuk informasi selengkapnya, lihat .NET.NET Aspire dan profil peluncuran.

Titik akhir yang telah dikonfigurasi oleh Kestrel

.NET .NET Aspire mendukung konfigurasi titik akhir Kestrel. Misalnya, pertimbangkan file appsettings.json untuk proyek yang menentukan titik akhir Kestrel dengan skema HTTPS dan port 5271:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5271"
      }
    }
  }
}

Konfigurasi sebelumnya menentukan titik akhir Https. Properti Url diatur ke https://*:5271, yang berarti titik akhir mendengarkan semua antarmuka pada port 5271. Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel.

Dengan titik akhir Kestrel yang sudah dikonfigurasi, proyek harus menghapus applicationUrl dari file launchSettings.json.

Saat Anda menambahkan sumber daya proyek, ada kelebihan beban yang memungkinkan Anda menentukan bahwa titik akhir Kestrel harus digunakan alih-alih file launchSettings.json:

builder.AddProject<Projects.Networking_ApiService>(
    name: "apiservice",
    configure: static project =>
    {
        project.ExcludeLaunchProfile = true;
        project.ExcludeKestrelEndpoints = false;
    })
    .WithHttpsEndpoint();

Untuk informasi selengkapnya, lihat AddProject.

Port dan proksi

Saat menentukan pengikatan layanan, port host selalu diberikan kepada proksi yang berada di depan layanan. Hal ini memungkinkan satu atau beberapa replika layanan berulah serupa. Selain itu, semua dependensi sumber daya yang menggunakan API WithReference mengandalkan titik akhir proksi dari variabel lingkungan.

Pertimbangkan rantai metode berikut yang memanggil AddProject, WithHttpEndpoint, lalu WithReplicas:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithReplicas(2);

Kode sebelumnya menghasilkan diagram jaringan berikut:

Diagram sebelumnya menggambarkan hal berikut:

• Browser web sebagai titik masuk ke aplikasi.
• Port untuk host 5066.
• Proksi frontend yang berada di antara browser web dan replika layanan frontend, mendengarkan di port 5066.
• Replika layanan frontend frontend_0 mendengarkan port 65001 yang ditetapkan secara acak.
• Replika layanan frontend frontend_1 mendengarkan port 65002 yang ditetapkan secara acak.

Jika tidak ada panggilan ke WithReplicas, hanya ada satu layanan frontend. Proksi masih mendengarkan port 5066, tetapi layanan frontend mendengarkan pada port acak:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066);

Ada dua port yang ditentukan:

• Port untuk host 5066.
• Port proksi acak yang akan diikat oleh layanan inti.

Diagram sebelumnya menggambarkan hal berikut:

• Browser web sebagai titik masuk ke aplikasi.
• Port untuk host 5066.
• Proksi frontend yang berada di antara browser web dan layanan frontend, yang memantau port 5066.
• Layanan frontend mendengarkan pada port yang dipilih secara acak, yaitu 65001.

Layanan dasar menerima port ini melalui ASPNETCORE_URLS untuk sumber daya proyek. Akses sumber daya lain ke port ini dengan menentukan variabel lingkungan pada pengikatan layanan:

builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
       .WithHttpEndpoint(port: 5067, env: "PORT");

Kode sebelumnya membuat port acak tersedia dalam variabel lingkungan PORT. Aplikasi ini menggunakan port ini untuk mendengarkan koneksi masuk dari proksi. Pertimbangkan diagram berikut:

Diagram sebelumnya menggambarkan hal berikut:

• Browser web sebagai titik masuk ke aplikasi.
• Port host dengan nomor 5067.
• Proksi frontend yang ditempatkan antara browser web dan layanan frontend, yang beroperasi pada port 5067.
• Layanan frontend mendengarkan lingkungan 65001.

Hilangkan port host

Saat Anda menghilangkan port host, .NET.NET Aspire menghasilkan port acak untuk port host dan layanan. Ini berguna ketika Anda ingin menghindari konflik port dan tidak peduli dengan host atau port layanan. Pertimbangkan kode berikut:

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint();

Dalam skenario ini, port host dan layanan acak, seperti yang ditunjukkan dalam diagram berikut:

Diagram sebelumnya menggambarkan hal berikut:

• Browser web sebagai titik masuk ke aplikasi.
• Port host dengan angka acak 65000.
• Proksi frontend yang terletak di antara browser web dan layanan frontend, beroperasi pada port 65000.
• Layanan frontend mendengarkan pada port acak di sekitar 65001.

Pelabuhan peti kemas

Saat Anda menambahkan sumber daya kontainer, .NET.NET Aspire secara otomatis menetapkan port acak ke kontainer. Untuk menentukan port kontainer, konfigurasikan sumber daya kontainer dengan port yang diinginkan:

builder.AddContainer("frontend", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
       .WithHttpEndpoint(port: 8000, targetPort: 8080);

Kode sebelumnya:

• Membuat sumber daya kontainer bernama frontend, dari gambar mcr.microsoft.com/dotnet/samples:aspnetapp.
• Mengekspos titik akhir http dengan mengikat host ke port 8000 dan memetakannya ke port kontainer 8080.

Pertimbangkan diagram berikut:

Metode ekstensi titik akhir

Sumber daya apa pun yang mengimplementasikan antarmuka IResourceWithEndpoints dapat menggunakan metode ekstensi WithEndpoint. Ada beberapa overload dari ekstensi ini, memungkinkan Anda menentukan skema, port kontainer, port host, nama variabel lingkungan, dan apakah titik akhir menggunakan proxy.

Ada juga kelebihan beban yang memungkinkan Anda menentukan delegasi untuk mengonfigurasi titik akhir. Ini berguna ketika Anda perlu mengonfigurasi titik akhir berdasarkan lingkungan atau faktor lain. Pertimbangkan kode berikut:

builder.AddProject<Projects.Networking_ApiService>("apiService")
       .WithEndpoint(
            endpointName: "admin",
            callback: static endpoint =>
       {
           endpoint.Port = 17003;
           endpoint.UriScheme = "http";
           endpoint.Transport = "http";
       });

Kode di atas menyediakan delegasi callback untuk mengonfigurasi endpoint. Titik akhir diberi nama admin dan dikonfigurasi untuk menggunakan skema dan transportasi http, serta port host 17003. Konsumen mereferensikan titik akhir ini berdasarkan nama, pertimbangkan panggilan AddHttpClient berikut:

builder.Services.AddHttpClient<WeatherApiClient>(
    client => client.BaseAddress = new Uri("http://_admin.apiservice"));

Uri dibangun menggunakan nama titik akhir admin yang diawali dengan sentinel _. Ini adalah konvensi untuk menunjukkan bahwa segmen admin adalah nama titik akhir milik layanan apiservice. Untuk informasi selengkapnya, lihat penemuan layanan .NET.NET Aspire.

Pertimbangan tambahan

Saat memanggil metode ekstensi WithEndpoint, kelebihan callback mengekspos EndpointAnnotationmentah , yang memungkinkan konsumen untuk menyesuaikan banyak aspek titik akhir.

Properti AllocatedEndpoint memungkinkan Anda mendapatkan atau mengatur titik akhir untuk layanan. Properti IsExternal dan IsProxied menentukan bagaimana titik akhir dikelola dan diekspos: IsExternal memutuskan apakah harus dapat diakses publik, sementara IsProxied memastikan DCP mengelolanya, memungkinkan perbedaan dan replikasi port internal.

Properti Name mengidentifikasi layanan, sedangkan properti Port dan TargetPort menentukan port yang dituju dan yang digunakan untuk mendengarkan.

Untuk komunikasi jaringan, properti Protocol mendukung TCP dan UDP , dengan potensi lebih banyak di masa mendatang, dan properti Transport menunjukkan protokol transportasi (HTTP, HTTP2 , HTTP3 ). Terakhir, jika layanan memiliki alamat URI, properti UriScheme menyediakan skema URI untuk membangun URI layanan.

Untuk informasi selengkapnya, lihat properti EndpointAnnotation yang tersedia.

Pemfilteran titik akhir

Semua titik akhir sumber daya proyek .NET.NET Aspire mengikuti serangkaian heuristik default. Beberapa titik akhir dimasukkan dalam ASPNETCORE_URLS saat waktu proses, beberapa dipublikasikan sebagai HTTP/HTTPS_PORTS, dan beberapa konfigurasi ditentukan dari konfigurasi Kestrel. Terlepas dari perilaku default, Anda dapat memfilter titik akhir yang disertakan dalam variabel lingkungan dengan menggunakan metode ekstensi WithEndpointsInEnvironment:

builder.AddProject<Projects.Networking_ApiService>("apiservice")
    .WithHttpsEndpoint() // Adds a default "https" endpoint
    .WithHttpsEndpoint(port: 19227, name: "admin")
    .WithEndpointsInEnvironment(
        filter: static endpoint =>
        {
            return endpoint.Name is not "admin";
        });

Kode sebelumnya menambahkan titik akhir HTTPS default, serta titik akhir admin pada port 19227. Namun, titik akhir admin dikecualikan dari variabel lingkungan. Ini berguna ketika Anda ingin mengekspos titik akhir hanya untuk penggunaan internal.