.NET .NET Aspire format manifes untuk penyusun alat penyebaran

Dalam artikel ini, Anda mempelajari tentang format manifes .NET.NET Aspire. Artikel ini berfungsi sebagai panduan referensi untuk penyusun alat penyebaran, membantu dalam pembuatan alat untuk menyebarkan proyek .NET.NET Aspire pada platform hosting tertentu, baik di tempat maupun di cloud.

.NET .NET Aspire menyederhanakan pengalaman pengembangan lokal dengan membantu mengelola interdependensi antara integrasi aplikasi. Untuk membantu menyederhanakan penyebaran aplikasi, proyek .NET Aspire dapat menghasilkan manifes semua sumber daya yang didefinisikan sebagai file berformat JSON.

Membuat manifes

Proyek .NET.NET Aspire yang valid diperlukan untuk menghasilkan manifes. Untuk memulai, buat proyek .NET.NET Aspire menggunakan templat aspire-starter.NET:

dotnet new aspire-starter --use-redis-cache `
    -o AspireApp && `
    cd AspireApp

Pembuatan manifes dicapai dengan menjalankan dotnet build dengan target khusus:

dotnet run --project AspireApp.AppHost\AspireApp.AppHost.csproj `
    --publisher manifest `
    --output-path ../aspire-manifest.json

Untuk informasi selengkapnya, lihat menjalankan dotnet. Perintah sebelumnya menghasilkan output berikut:

Building...
info: Aspire.Hosting.Publishing.ManifestPublisher[0]
      Published manifest to: .\AspireApp.AppHost\aspire-manifest.json

File yang dihasilkan adalah manifes .NET.NET Aspire dan digunakan oleh alat untuk mendukung penyebaran ke lingkungan cloud target.

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "generate-manifest": {
      "commandName": "Project",
      "launchBrowser": false,
      "dotnetRunMessages": true,
      "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json"
    }
  }
}

Format manifes dasar

Menerbitkan manifes dari templat pemula default untuk .NET Aspire menghasilkan output JSON berikut:

{
  "resources": {
    "cache": {
      "type": "container.v0",
      "connectionString": "{cache.bindings.tcp.host}:{cache.bindings.tcp.port}",
      "image": "redis:7.2.4",
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 6379
        }
      }
    },
    "apiservice": {
      "type": "project.v0",
      "path": "../AspireApp.ApiService/AspireApp.ApiService.csproj",
      "env": {
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http"
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http"
        }
      }
    },
    "webfrontend": {
      "type": "project.v0",
      "path": "../AspireApp.Web/AspireApp.Web.csproj",
      "env": {
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
        "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true",
        "ConnectionStrings__cache": "{cache.connectionString}",
        "services__apiservice__0": "{apiservice.bindings.http.url}",
        "services__apiservice__1": "{apiservice.bindings.https.url}"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http"
        },
        "https": {
          "scheme": "https",
          "protocol": "tcp",
          "transport": "http"
        }
      }
    }
  }
}

Format manifes JSON terdiri dari satu objek yang disebut resources, yang berisi properti untuk setiap sumber daya yang ditentukan dalam Program.cs (argumen name untuk setiap nama digunakan sebagai properti untuk setiap objek sumber daya anak di JSON).

String koneksi dan referensi pengikatan

Dalam contoh sebelumnya, ada dua sumber daya proyek dan satu sumber daya cache Redis. webfrontend bergantung pada sumber daya apiservice (proyek) dan cache ().

Dependensi ini diketahui karena variabel lingkungan untuk webfrontend berisi tempat penampung yang mereferensikan dua sumber daya lainnya:

"env": {
  // ... other environment variables omitted for clarity
  "ConnectionStrings__cache": "{cache.connectionString}",
  "services__apiservice__0": "{apiservice.bindings.http.url}",
  "services__apiservice__1": "{apiservice.bindings.https.url}"
},

Sumber daya apiservice dirujuk oleh webfrontend menggunakan WithReference(apiservice) panggilan di file Program.cs host aplikasi dan redis dirujuk menggunakan panggilan WithReference(cache):

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithReference(cache)
    .WithReference(apiService);

builder.Build().Run();

Referensi antara jenis sumber daya proyek menghasilkan penemuan layanan variabel yang disuntikkan ke dalam proyek referensi. Referensi ke jenis referensi terkenal seperti Redis mengakibatkan string koneksi disuntikkan.

Untuk informasi selengkapnya tentang cara kerja sumber daya dalam model aplikasi dan referensi di antara mereka, lihat, .NET.NET Aspire gambaran umum orkestrasi.

Struktur string tempat penampung

String tempat penampung mereferensikan struktur manifes .NET.NET Aspire:

Segmen akhir string tempat penampung (url dalam hal ini) dihasilkan oleh alat yang memproses manifes. Ada beberapa akhiran yang dapat digunakan pada string tempat penampung:

• connectionString: Untuk jenis sumber daya terkenal seperti Redis. Alat penyebaran menerjemahkan sumber daya dalam infrastruktur yang paling sesuai untuk lingkungan cloud target lalu menghasilkan string koneksi yang kompatibel .NET.NET Aspire agar aplikasi yang menggunakannya. Pada sumber daya container.v0 bidang connectionString mungkin ada dan ditentukan secara eksplisit. Ini untuk mendukung skenario di mana jenis sumber daya kontainer direferensikan menggunakan ekstensi WithReference tetapi diinginkan untuk dihosting secara eksplisit sebagai kontainer.
• url: Untuk referensi layanan-ke-layanan di mana URL yang terbentuk dengan baik diperlukan. Alat penyebaran menghasilkan url berdasarkan skema, protokol, dan transportasi yang ditentukan dalam manifes dan topologi komputasi/jaringan dasar yang disebarkan.
• host: Segmen host URL.
• port: Segmen port URL.

Jenis sumber daya

Setiap sumber daya memiliki bidang type. Ketika alat penyebaran membaca manifes, alat tersebut harus membaca jenis untuk memverifikasi apakah alat penyebaran dapat memproses manifes dengan benar. Selama periode pratinjau .NET.NET Aspire, semua jenis sumber daya memiliki akhiran v0 untuk menunjukkan bahwa jenis sumber daya tersebut dapat berubah. Saat pendekatan .NET.NET Aspire merilis akhiran v1 akan digunakan untuk menandakan bahwa struktur manifes untuk jenis sumber daya tersebut harus dianggap stabil (pembaruan berikutnya menaikkan nomor versi yang sesuai).

Bidang sumber daya umum

Bidang type adalah satu-satunya bidang yang umum di semua jenis sumber daya, namun, jenis sumber daya project.v0, container.v0, dan executable.v0 juga berbagi bidang env dan bindings.

Jenis bidang env adalah pemetaan kunci/nilai dasar di mana nilai mungkin berisi string tempat penampung .

Pengikatan ditentukan dalam bidang bindings dengan setiap pengikatan yang terkandung dalam bidangnya sendiri di bawah objek bindingsJSON. Bidang yang dihilangkan oleh manifes .NET.NET Aspire dalam simpul bindings meliputi:

• scheme: Salah satu nilai berikut tcp, udp, http, atau https.
• protocol: Salah satu nilai berikut tcp atau udp
• transport: Sama seperti scheme, tetapi digunakan untuk membedakan antara http dan http2.
• containerPort: Opsional, jika dihilangkan default ke port 80.

Bidang inputs

Beberapa sumber daya menghasilkan bidang inputs. Bidang ini digunakan untuk menentukan parameter input untuk sumber daya. Bidang inputs adalah objek JSON di mana setiap properti adalah parameter input yang digunakan dalam resolusi struktur tempat penampung. Sumber daya yang memiliki connectionString, misalnya, mungkin menggunakan bidang inputs untuk menentukan password untuk string koneksi:

"connectionString": "Host={<resourceName>.bindings.tcp.host};Port={<resourceName>.bindings.tcp.port};Username=admin;Password={<resourceName>.inputs.password};"

Tempat penampung string koneksi mereferensikan parameter input password dari bidang inputs:

"inputs": {
  "password": {
    "type": "string",
    "secret": true,
    "default": {
      "generate": {
        "minLength": 10
      }
    }
  }
}

Cuplikan JSON sebelumnya memperlihatkan bidang inputs untuk sumber daya yang memiliki bidang connectionString. Parameter input password adalah jenis string dan ditandai sebagai rahasia. Bidang default digunakan untuk menentukan nilai default untuk parameter input. Dalam hal ini, nilai default dihasilkan menggunakan bidang generate, dengan string acak dengan panjang minimum.

Sumber daya bawaan

Tabel berikut adalah daftar jenis sumber daya yang dihasilkan secara eksplisit oleh .NET Aspire dan ekstensi yang dikembangkan oleh tim .NET Aspire:

Jenis sumber daya cloud-agnostik

Sumber daya ini tersedia di 📦Aspire. Hosting paket NuGet.

Jenis sumber daya proyek

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

Contoh manifes:

"apiservice": {
  "type": "project.v0",
  "path": "../AspireApp.ApiService/AspireApp.ApiService.csproj",
  "env": {
    "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true",
    "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true"
  },
  "bindings": {
    "http": {
      "scheme": "http",
      "protocol": "tcp",
      "transport": "http"
    },
    "https": {
      "scheme": "https",
      "protocol": "tcp",
      "transport": "http"
    }
  }
}

Jenis sumber daya kontainer

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddContainer("mycontainer", "myimage")
       .WithEnvironment("LOG_LEVEL", "WARN")
       .WithHttpEndpoint(3000);

Contoh manifes:

{
  "resources": {
    "mycontainer": {
      "type": "container.v0",
      "image": "myimage:latest",
      "env": {
        "LOG_LEVEL": "WARN"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http",
          "containerPort": 3000
        }
      }
    }
  }
}

Dockerfile jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddNodeApp("nodeapp", "../nodeapp/app.js")
       .WithHttpEndpoint(hostPort: 5031, env: "PORT")
       .PublishAsDockerFile();

Contoh manifes:

{
  "resources": {
    "nodeapp": {
      "type": "dockerfile.v0",
      "path": "../nodeapp/Dockerfile",
      "context": "../nodeapp",
      "env": {
        "NODE_ENV": "development",
        "PORT": "{nodeapp.bindings.http.port}"
      },
      "bindings": {
        "http": {
          "scheme": "http",
          "protocol": "tcp",
          "transport": "http",
          "containerPort": 5031
        }
      }
    }
  }
}

Postgres jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddPostgres("postgres1")
       .AddDatabase("shipping");

Contoh manifes:

{
  "resources": {
    "postgres1": {
      "type": "container.v0",
      "connectionString": "Host={postgres1.bindings.tcp.host};Port={postgres1.bindings.tcp.port};Username=postgres;Password={postgres1.inputs.password}",
      "image": "postgres:16.2",
      "env": {
        "POSTGRES_HOST_AUTH_METHOD": "scram-sha-256",
        "POSTGRES_INITDB_ARGS": "--auth-host=scram-sha-256 --auth-local=scram-sha-256",
        "POSTGRES_PASSWORD": "{postgres1.inputs.password}"
      },
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 5432
        }
      },
      "inputs": {
        "password": {
          "type": "string",
          "secret": true,
          "default": {
            "generate": {
              "minLength": 10
            }
          }
        }
      }
    },
    "shipping": {
      "type": "value.v0",
      "connectionString": "{postgres1.connectionString};Database=shipping"
    }
  }
}

RabbitMQ jenis sumber daya

RabbitMQ dimodelkan sebagai sumber daya kontainer container.v0. Sampel berikut menunjukkan cara menambahkannya ke model aplikasi.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddRabbitMQ("rabbitmq1");

Kode sebelumnya menghasilkan manifes berikut:

{
  "resources": {
    "rabbitmq1": {
      "type": "container.v0",
      "connectionString": "amqp://guest:{rabbitmq1.inputs.password}@{rabbitmq1.bindings.tcp.host}:{rabbitmq1.bindings.tcp.port}",
      "image": "rabbitmq:3",
      "env": {
        "RABBITMQ_DEFAULT_USER": "guest",
        "RABBITMQ_DEFAULT_PASS": "{rabbitmq1.inputs.password}"
      },
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 5672
        }
      },
      "inputs": {
        "password": {
          "type": "string",
          "secret": true,
          "default": {
            "generate": {
              "minLength": 10
            }
          }
        }
      }
    }
  }
}

jenis sumber daya Redis

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddRedis("redis1");

Contoh manifes:

{
  "resources": {
    "redis1": {
      "type": "container.v0",
      "connectionString": "{redis1.bindings.tcp.host}:{redis1.bindings.tcp.port}",
      "image": "redis:7.2.4",
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 6379
        }
      }
    }
  }
}

SQL Server jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddSqlServer("sql1")
       .AddDatabase("shipping");

Contoh manifes:

{
  "resources": {
    "sql1": {
      "type": "container.v0",
      "connectionString": "Server={sql1.bindings.tcp.host},{sql1.bindings.tcp.port};User ID=sa;Password={sql1.inputs.password};TrustServerCertificate=true",
      "image": "mcr.microsoft.com/mssql/server:2022-latest",
      "env": {
        "ACCEPT_EULA": "Y",
        "MSSQL_SA_PASSWORD": "{sql1.inputs.password}"
      },
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 1433
        }
      },
      "inputs": {
        "password": {
          "type": "string",
          "secret": true,
          "default": {
            "generate": {
              "minLength": 10
            }
          }
        }
      }
    },
    "shipping": {
      "type": "value.v0",
      "connectionString": "{sql1.connectionString};Database=shipping"
    }
  }
}

MongoDB jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddMongoDB("mongodb1")
       .AddDatabase("shipping");

Contoh manifes:

{
  "resources": {
    "mongodb1": {
      "type": "container.v0",
      "connectionString": "mongodb://{mongodb1.bindings.tcp.host}:{mongodb1.bindings.tcp.port}",
      "image": "mongo:7.0.5",
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 27017
        }
      }
    },
    "shipping": {
      "type": "value.v0",
      "connectionString": "{mongodb1.connectionString}/shipping"
    }
  }
}

MySQL jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddMySql("mysql1")
       .AddDatabase("shipping");

Contoh manifes:

{
  "resources": {
    "mysql1": {
      "type": "container.v0",
      "connectionString": "Server={mysql1.bindings.tcp.host};Port={mysql1.bindings.tcp.port};User ID=root;Password={mysql1.inputs.password}",
      "image": "mysql:8.3.0",
      "env": {
        "MYSQL_ROOT_PASSWORD": "{mysql1.inputs.password}"
      },
      "bindings": {
        "tcp": {
          "scheme": "tcp",
          "protocol": "tcp",
          "transport": "tcp",
          "containerPort": 3306
        }
      },
      "inputs": {
        "password": {
          "type": "string",
          "secret": true,
          "default": {
            "generate": {
              "minLength": 10
            }
          }
        }
      }
    },
    "shipping": {
      "type": "value.v0",
      "connectionString": "{mysql1.connectionString};Database=shipping"
    }
  }
}

Azure-jenis sumber daya tertentu

Sumber daya berikut tersedia di 📦Aspire. Hosting.Azure paket NuGet.

jenis sumber daya Azure Key Vault

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureKeyVault("keyvault1");

Contoh manifes:

{
  "resources": {
    "keyvault1": {
      "type": "azure.bicep.v0",
      "connectionString": "{keyvault1.outputs.vaultUri}",
      "path": "aspire.hosting.azure.bicep.keyvault.bicep",
      "params": {
        "principalId": "",
        "principalType": "",
        "vaultName": "keyvault1"
      }
    }
  }
}

jenis sumber daya Azure Service Bus

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureServiceBus("sb1")
       .AddTopic("topic1", [])
       .AddTopic("topic2", [])
       .AddQueue("queue1")
       .AddQueue("queue2");

Contoh manifes:

{
  "resources": {
    "sb1": {
      "type": "azure.bicep.v0",
      "connectionString": "{sb1.outputs.serviceBusEndpoint}",
      "path": "aspire.hosting.azure.bicep.servicebus.bicep",
      "params": {
        "serviceBusNamespaceName": "sb1",
        "principalId": "",
        "principalType": "",
        "queues": [
          "queue1",
          "queue2"
        ],
        "topics": [
          {
            "name": "topic1",
            "subscriptions": []
          },
          {
            "name": "topic2",
            "subscriptions": []
          }
        ]
      }
    }
  }
}

jenis sumber daya Azure Storage

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("images");

storage.AddBlobs("blobs");
storage.AddQueues("queues");
storage.AddTables("tables");

Contoh manifes:

{
  "resources": {
    "images": {
      "type": "azure.bicep.v0",
      "path": "aspire.hosting.azure.bicep.storage.bicep",
      "params": {
        "principalId": "",
        "principalType": "",
        "storageName": "images"
      }
    },
    "blobs": {
      "type": "value.v0",
      "connectionString": "{images.outputs.blobEndpoint}"
    },
    "queues": {
      "type": "value.v0",
      "connectionString": "{images.outputs.queueEndpoint}"
    },
    "tables": {
      "type": "value.v0",
      "connectionString": "{images.outputs.tableEndpoint}"
    }
  }
}

jenis sumber daya AzureRedis

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureRedis("azredis1");

Contoh manifes:

{
  "resources": {
    "azredis": {
      "type": "azure.bicep.v0",
      "connectionString": "{azredis.outputs.connectionString}",
      "path": "azredis.module.bicep",
      "params": {
        "principalId": "",
        "principalName": ""
      }
    }
  }
}

Azure jenis sumber daya App Configuration

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureAppConfiguration("appconfig1");

Contoh manifes:

{
  "resources": {
    "appconfig1": {
      "type": "azure.bicep.v0",
      "connectionString": "{appconfig1.outputs.appConfigEndpoint}",
      "path": "aspire.hosting.azure.bicep.appconfig.bicep",
      "params": {
        "configName": "appconfig1",
        "principalId": "",
        "principalType": ""
      }
    }
  }
}

Azure jenis sumber daya SQL

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureSqlServer("sql")
       .AddDatabase("inventory");

Contoh manifes:

{
  "resources": {
    "sql": {
      "type": "azure.bicep.v0",
      "connectionString": "Server=tcp:{sql.outputs.sqlServerFqdn},1433;Encrypt=True;Authentication=\u0022Active Directory Default\u0022",
      "path": "sql.module.bicep",
      "params": {
        "principalId": "",
        "principalName": ""
      }
    },
    "inventory": {
      "type": "value.v0",
      "connectionString": "{sql.connectionString};Database=inventory"
    }
  }
}

Azure Postgres jenis sumber daya

Contoh kode:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzurePostgresFlexibleServer("postgres")
       .AddDatabase("db");

Contoh manifes:

{
  "resources": {
    "postgres": {
      "type": "azure.bicep.v0",
      "connectionString": "{postgres.outputs.connectionString}",
      "path": "postgres.module.bicep",
      "params": {
        "principalId": "",
        "principalType": "",
        "principalName": ""
      }
    },
    "db": {
      "type": "value.v0",
      "connectionString": "{postgres.connectionString};Database=db"
    }
  }
}

Jenis sumber daya yang didukung di Azure Developer CLI

Azure Developer CLI (azd) adalah alat yang dapat digunakan untuk menyebarkan proyek .NET Aspire ke Azure Container Apps. Dengan jenis sumber daya azure.bicep.v0, jenis kontainer sumber daya cloud-agnostik dapat dipetakan ke sumber daya Azure-spesifik. Tabel berikut ini mencantumkan jenis sumber daya yang didukung di Azure Developer CLI:

Saat sumber daya dikonfigurasi sebagai sumber daya Azure, jenis sumber daya azure.bicep.v0 dihasilkan dalam manifes. Untuk informasi selengkapnya, lihat .NET AspireAzure Container Apps (panduan mendalam) Azure Container Apps .

Lihat juga

• gambaran umum
• gambaran umum orkestrasi
• gambaran umum integrasi
• penemuan Layanan di .NET.NET Aspire