Rychlý start: Vytvoření nového projektu rozhraní API pomocí TypeSpec a .NET

V tomto rychlém startu se dozvíte, jak pomocí TypeSpec navrhovat, generovat a implementovat aplikaci RESTful API. TypeSpec je opensourcový jazyk pro popis rozhraní API cloudové služby a generuje kód klienta a serveru pro více platforem. V tomto rychlém startu se dozvíte, jak definovat kontrakt rozhraní API jednou a generovat konzistentní implementace, což vám pomůže vytvářet lépe udržovatelné a dobře zdokumentované služby rozhraní API.

V tomto rychlém průvodci vám:

• Definování rozhraní API pomocí TypeSpec
• Vytvoření serverové aplikace rozhraní API
• Integrace služby Azure Cosmos DB pro trvalé úložiště
• Místní spuštění a otestování rozhraní API
• Nasazení do aplikací Azure Container Apps

Prerequisites

• Aktivní účet Azure. Pokud ho nemáte, vytvořte si účet zdarma .
• Sada .NET 9 SDK
• Node.js LTS nainstalované ve vašem systému.
• Visual Studio Code s následujícími rozšířeními:
• Rozšíření TypeSpec
• Volitelné: Nasazení pomocí Azure Developer CLI

Vývoj pomocí TypeSpec

TypeSpec definuje vaše rozhraní API nezávislou na jazyce a vygeneruje server rozhraní API a klientskou knihovnu pro více platforem. Tato funkce umožňuje:

• Definujte kontrakt rozhraní API jenom jednou
• Generování konzistentního serveru a klientského kódu
• Zaměřte se na implementaci obchodní logiky místo infrastruktury rozhraní API.

TypeSpec poskytuje správu služeb pro API:

• Jazyk definice rozhraní API
• Middleware pro směrování na serverové straně pro rozhraní API
• Klientské knihovny pro využívání rozhraní API

Poskytujete požadavky klientů a integraci serverů:

• Implementace obchodní logiky v middlewaru, jako jsou služby Azure pro databáze, úložiště a zasílání zpráv
• Hostování serveru pro vaše rozhraní API (místně nebo v Azure)
• Skripty nasazení pro opakovatelné zřizování a nasazení

Vytvoření nové aplikace TypeSpec

1. Vytvořte novou složku pro uložení serveru rozhraní API a souborů TypeSpec.

   mkdir my_typespec_quickstart
   cd my_typespec_quickstart
   

2. Globální instalace kompilátoru TypeSpec :

   npm install -g @typespec/compiler
   

3. Zkontrolujte, jestli je TypeSpec správně nainstalovaný:

   tsp --version
   

4. Inicializace projektu TypeSpec:

   tsp init
   

5. Odpovězte na následující otázky pomocí poskytnutých odpovědí.

   • Inicializujete tady nový projekt? Y
   • Vyberte šablonu projektu? Obecné rozhraní REST API
   • Zadejte název projektu: Widgety
   • Jaké emitory chcete použít?
     • Dokument OpenAPI 3.1
     • Zástupný kód serveru C#

   Emitory TypeSpec jsou knihovny, které využívají různá rozhraní API kompilátoru TypeSpec pro reflektování procesu kompilace TypeSpec a generování artefaktů.

6. Než budete pokračovat, počkejte na dokončení inicializace.

   Run tsp compile . to build the project.
   
   Please review the following messages from emitters:
     @typespec/http-server-csharp: 
   
           Generated ASP.Net services require dotnet 9:
           https://dotnet.microsoft.com/download 
   
           Create an ASP.Net service project for your TypeSpec:
           > npx hscs-scaffold . --use-swaggerui --overwrite
   
           More information on getting started:
           https://aka.ms/tsp/hscs/start
   

7. Zkompilujte projekt:

   tsp compile .
   

8. TypeSpec vygeneruje výchozí projekt v ./tsp-output, vytvoření dvou samostatných složek:

   • schéma
   • server

9. Otevřete soubor ./tsp-output/schema/openapi.yaml. Všimněte si, že několik řádků v ./main.tsp vygenerovalo více než 200 řádků specifikace OpenApi za vás.

10. ./tsp-output/server/aspnet Otevřete složku. Všimněte si, že strukturální soubory .NET zahrnují:

    • ./generated/operations/IWidgets.cs definuje rozhraní pro metody Widgets.
    • ./generated/controllers/WidgetsController.cs implementuje integraci do metod Widgets. Tady umístíte obchodní logiku.
    • ./generated/models definuje modely pro rozhraní API widgetu.

Konfigurace emitorů TypeSpec

Ke konfiguraci generování serveru API použijte soubory TypeSpec.

1. Otevřete tsconfig.yaml a nahraďte stávající konfiguraci následujícím YAML:

   emit:
     - "@typespec/openapi3"
     - "@typespec/http-server-csharp"
   options:
     "@typespec/openapi3":
       emitter-output-dir: "{cwd}/server/wwwroot"
       openapi-versions:
         - 3.1.0
     "@typespec/http-server-csharp":
       emitter-output-dir: "{cwd}/server/"
       use-swaggerui: true
       overwrite: true
       emit-mocks: "mocks-and-project-files"
   

   Tato konfigurace zahrnuje několik změn, které potřebujeme pro plně vygenerovaný .NET API server.

   • emit-mocks: Vytvořte všechny soubory projektu potřebné pro server.
   • use-swaggerui: Integrujte uživatelské rozhraní Swagger, abyste mohli rozhraní API používat v prohlížeči.
   • emitter-output-dir: Nastavte výstupní adresář jak pro generování serveru, tak pro specifikaci OpenApi.
   • Vygenerujte vše do ./server.

2. Překompilujte projekt:

   tsp compile .
   

3. Přejděte do nového /server adresáře:

   cd server
   

4. Pokud ho ještě nemáte, vytvořte výchozí vývojářský certifikát:

   dotnet dev-certs https
   

5. Spusťte projekt:

   dotnet run
   

   Počkejte, až se oznámení otevře v prohlížeči.

6. Otevřete prohlížeč a přidejte trasu uživatelského rozhraní Swagger, /swagger.

   

7. Výchozí rozhraní API TypeSpec i server fungují.

Principy struktury souborů aplikace

Struktura projektu pro vygenerovaný server zahrnuje server rozhraní API založený na kontroleru .NET, soubory .NET pro sestavení projektu a middleware pro integraci Azure.

├── appsettings.Development.json
├── appsettings.json
├── docs
├── generated
├── mocks
├── Program.cs
├── Properties
├── README.md
├── ServiceProject.csproj
└── wwwroot

• Přidejte obchodní logiku: v tomto příkladu začněte se souborem ./server/mocks/Widget.cs . Generovaná Widget.cs poskytuje výchozí metody.
• Aktualizujte server: Přidejte do ./program.cssouboru všechny konkrétní konfigurace serveru .
• Použijte specifikaci OpenApi: TypeSpec vygeneroval soubor OpenApi3.json do ./server/wwwroot souboru a během vývoje ho zpřístupnil uživatelskému rozhraní Swagger. Poskytuje uživatelské rozhraní pro vaši specifikaci. S rozhraním API můžete pracovat, aniž byste museli poskytovat mechanismus požadavků, jako je klient REST nebo webový front-end.

Změna trvalosti na Azure Cosmos DB no-sql

Když teď funguje základní server rozhraní API widgetu, aktualizujte server tak, aby fungoval se službou Azure Cosmos DB pro trvalé úložiště dat.

1. ./server V adresáři přidejte do projektu Službu Azure Cosmos DB:

   dotnet add package Microsoft.Azure.Cosmos
   

2. Přidejte knihovnu Identit Azure pro ověření do Azure:

   dotnet add package Azure.Identity
   

3. ./server/ServiceProject.csproj Aktualizujte nastavení integrace služby Cosmos DB:

   <Project Sdk="Microsoft.NET.Sdk.Web">
     <PropertyGroup>
       ... existing settings ...
       <EnableSdkContainerSupport>true</EnableSdkContainerSupport>
     </PropertyGroup>
     <ItemGroup>
       ... existing settings ...
       <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     </ItemGroup>
   </Project>
   

   • EnableSdkContainerSupport umožňuje používat integrovanou podporu sestavení kontejneru sady .NET SDK (dotnet publish ––container) bez zápisu souboru Dockerfile.
   • Newtonsoft.Json přidá serializátor Json .NET, který sada SDK služby Cosmos DB používá k převodu objektů .NET do a z JSON.

4. Vytvořte nový registrační soubor pro ./azure/CosmosDbRegistration správu registrace služby Cosmos DB:

   using Microsoft.Azure.Cosmos;
   using Microsoft.Extensions.Configuration;
   using System;
   using System.Threading.Tasks;
   using Azure.Identity;
   using DemoService;
   
   namespace WidgetService.Service
   {
       /// <summary>
       /// Registration class for Azure Cosmos DB services and implementations
       /// </summary>
       public static class CosmosDbRegistration
       {
           /// <summary>
           /// Registers the Cosmos DB client and related services for dependency injection
           /// </summary>
           /// <param name="builder">The web application builder</param>
           public static void RegisterCosmosServices(this WebApplicationBuilder builder)
           {
               // Register the HttpContextAccessor for accessing the HTTP context
               builder.Services.AddHttpContextAccessor();
   
               // Get configuration settings
               var cosmosEndpoint = builder.Configuration["Configuration:AzureCosmosDb:Endpoint"];
   
               // Validate configuration
               ValidateCosmosDbConfiguration(cosmosEndpoint);
   
               // Configure Cosmos DB client options
               var cosmosClientOptions = new CosmosClientOptions
               {
                   SerializerOptions = new CosmosSerializationOptions
                   {
                       PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
                   },
                   ConnectionMode = ConnectionMode.Direct
               };
   
               builder.Services.AddSingleton(serviceProvider =>
               {
                   var credential = new DefaultAzureCredential();
   
                   // Create Cosmos client with token credential authentication
                   return new CosmosClient(cosmosEndpoint, credential, cosmosClientOptions);
               });
   
               // Initialize Cosmos DB if needed
               builder.Services.AddHostedService<CosmosDbInitializer>();
   
               // Register WidgetsCosmos implementation of IWidgets
               builder.Services.AddScoped<IWidgets, WidgetsCosmos>();
           }
   
           /// <summary>
           /// Validates the Cosmos DB configuration settings
           /// </summary>
           /// <param name="cosmosEndpoint">The Cosmos DB endpoint</param>
           /// <exception cref="ArgumentException">Thrown when configuration is invalid</exception>
           private static void ValidateCosmosDbConfiguration(string cosmosEndpoint)
           {
               if (string.IsNullOrEmpty(cosmosEndpoint))
               {
                   throw new ArgumentException("Cosmos DB Endpoint must be specified in configuration");
               }
           }
       }
   }
   

   Všimněte si proměnné prostředí pro koncový bod:

   var cosmosEndpoint = builder.Configuration["Configuration:AzureCosmosDb:Endpoint"];
   

5. Vytvořte novou třídu widgetu, ./azure/WidgetsCosmos.cs která poskytuje obchodní logiku pro integraci se službou Azure Cosmos DB pro trvalé úložiště.

   using System;
   using System.Net;
   using System.Threading.Tasks;
   using Microsoft.Azure.Cosmos;
   using Microsoft.Extensions.Logging;
   using System.Collections.Generic;
   using System.Linq;
   
   // Use generated models and operations
   using DemoService;
   
   namespace WidgetService.Service
   {
       /// <summary>
       /// Implementation of the IWidgets interface that uses Azure Cosmos DB for persistence
       /// </summary>
       public class WidgetsCosmos : IWidgets
       {
           private readonly CosmosClient _cosmosClient;
           private readonly ILogger<WidgetsCosmos> _logger;
           private readonly IHttpContextAccessor _httpContextAccessor;
           private readonly string _databaseName = "WidgetDb";
           private readonly string _containerName = "Widgets";
   
           /// <summary>
           /// Initializes a new instance of the WidgetsCosmos class.
           /// </summary>
           /// <param name="cosmosClient">The Cosmos DB client instance</param>
           /// <param name="logger">Logger for diagnostic information</param>
           /// <param name="httpContextAccessor">Accessor for the HTTP context</param>
           public WidgetsCosmos(
               CosmosClient cosmosClient,
               ILogger<WidgetsCosmos> logger,
               IHttpContextAccessor httpContextAccessor)
           {
               _cosmosClient = cosmosClient;
               _logger = logger;
               _httpContextAccessor = httpContextAccessor;
           }
   
           /// <summary>
           /// Gets a reference to the Cosmos DB container for widgets
           /// </summary>
           private Container WidgetsContainer => _cosmosClient.GetContainer(_databaseName, _containerName);
   
           /// <summary>
           /// Lists all widgets in the database
           /// </summary>
           /// <returns>Array of Widget objects</returns>
           public async Task<WidgetList> ListAsync()
           {
               try
               {
                   var queryDefinition = new QueryDefinition("SELECT * FROM c");
                   var widgets = new List<Widget>();
   
                   using var iterator = WidgetsContainer.GetItemQueryIterator<Widget>(queryDefinition);
                   while (iterator.HasMoreResults)
                   {
                       var response = await iterator.ReadNextAsync();
                       widgets.AddRange(response.ToList());
                   }
   
                   // Create and return a WidgetList instead of Widget[]
                   return new WidgetList
                   {
                       Items = widgets.ToArray()
                   };
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error listing widgets from Cosmos DB");
                   throw new Error(500, "Failed to retrieve widgets from database");
               }
           }
   
           /// <summary>
           /// Retrieves a specific widget by ID
           /// </summary>
           /// <param name="id">The ID of the widget to retrieve</param>
           /// <returns>The retrieved Widget</returns>
           public async Task<Widget> ReadAsync(string id)
           {
               try
               {
                   var response = await WidgetsContainer.ReadItemAsync<Widget>(
                       id, new PartitionKey(id));
   
                   return response.Resource;
               }
               catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
               {
                   _logger.LogWarning("Widget with ID {WidgetId} not found", id);
                   throw new Error(404, $"Widget with ID '{id}' not found");
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error reading widget {WidgetId} from Cosmos DB", id);
                   throw new Error(500, "Failed to retrieve widget from database");
               }
           }
           /// <summary>
           /// Creates a new widget from the provided Widget object
           /// </summary>
           /// <param name="body">The Widget object to store in the database</param>
           /// <returns>The created Widget</returns>
           public async Task<Widget> CreateAsync(Widget body)
           {
               try
               {
                   // Validate the Widget
                   if (body == null)
                   {
                       throw new Error(400, "Widget data cannot be null");
                   }
   
                   if (string.IsNullOrEmpty(body.Id))
                   {
                       throw new Error(400, "Widget must have an Id");
                   }
   
                   if (body.Color != "red" && body.Color != "blue")
                   {
                       throw new Error(400, "Color must be 'red' or 'blue'");
                   }
   
                   // Save the widget to Cosmos DB
                   var response = await WidgetsContainer.CreateItemAsync(
                       body, new PartitionKey(body.Id));
   
                   _logger.LogInformation("Created widget with ID {WidgetId}", body.Id);
                   return response.Resource;
               }
               catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
               {
                   _logger.LogError(ex, "Widget with ID {WidgetId} already exists", body.Id);
                   throw new Error(409, $"Widget with ID '{body.Id}' already exists");
               }
               catch (Exception ex) when (!(ex is Error))
               {
                   _logger.LogError(ex, "Error creating widget in Cosmos DB");
                   throw new Error(500, "Failed to create widget in database");
               }
           }
   
           /// <summary>
           /// Updates an existing widget with properties specified in the patch document
           /// </summary>
           /// <param name="id">The ID of the widget to update</param>
           /// <param name="body">The WidgetMergePatchUpdate object containing properties to update</param>
           /// <returns>The updated Widget</returns>
           public async Task<Widget> UpdateAsync(string id, TypeSpec.Http.WidgetMergePatchUpdate body)
           {
               try
               {
                   // Validate input parameters
                   if (body == null)
                   {
                       throw new Error(400, "Update data cannot be null");
                   }
   
                   if (body.Color != null && body.Color != "red" && body.Color != "blue")
                   {
                       throw new Error(400, "Color must be 'red' or 'blue'");
                   }
   
                   // First check if the item exists
                   Widget existingWidget;
                   try
                   {
                       var response = await WidgetsContainer.ReadItemAsync<Widget>(
                           id, new PartitionKey(id));
                       existingWidget = response.Resource;
                   }
                   catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
                   {
                       _logger.LogWarning("Widget with ID {WidgetId} not found for update", id);
                       throw new Error(404, $"Widget with ID '{id}' not found");
                   }
   
                   // Apply the patch updates only where properties are provided
                   bool hasChanges = false;
   
                   if (body.Weight.HasValue)
                   {
                       existingWidget.Weight = body.Weight.Value;
                       hasChanges = true;
                   }
   
                   if (body.Color != null)
                   {
                       existingWidget.Color = body.Color;
                       hasChanges = true;
                   }
   
                   // Only perform the update if changes were made
                   if (hasChanges)
                   {
                       // Use ReplaceItemAsync for the update
                       var updateResponse = await WidgetsContainer.ReplaceItemAsync(
                           existingWidget, id, new PartitionKey(id));
   
                       _logger.LogInformation("Updated widget with ID {WidgetId}", id);
                       return updateResponse.Resource;
                   }
   
                   // If no changes, return the existing widget
                   _logger.LogInformation("No changes to apply for widget with ID {WidgetId}", id);
                   return existingWidget;
               }
               catch (Error)
               {
                   // Rethrow Error exceptions
                   throw;
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error updating widget {WidgetId} in Cosmos DB", id);
                   throw new Error(500, "Failed to update widget in database");
               }
           }
   
           /// <summary>
           /// Deletes a widget by its ID
           /// </summary>
           /// <param name="id">The ID of the widget to delete</param>
           public async Task DeleteAsync(string id)
           {
               try
               {
                   await WidgetsContainer.DeleteItemAsync<Widget>(id, new PartitionKey(id));
                   _logger.LogInformation("Deleted widget with ID {WidgetId}", id);
               }
               catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
               {
                   _logger.LogWarning("Widget with ID {WidgetId} not found for deletion", id);
                   throw new Error(404, $"Widget with ID '{id}' not found");
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error deleting widget {WidgetId} from Cosmos DB", id);
                   throw new Error(500, "Failed to delete widget from database");
               }
           }
   
           /// <summary>
           /// Analyzes a widget by ID and returns a simplified analysis result
           /// </summary>
           /// <param name="id">The ID of the widget to analyze</param>
           /// <returns>An AnalyzeResult containing the analysis of the widget</returns>
           public async Task<AnalyzeResult> AnalyzeAsync(string id)
           {
               try
               {
                   // First retrieve the widget from the database
                   Widget widget;
                   try
                   {
                       var response = await WidgetsContainer.ReadItemAsync<Widget>(
                           id, new PartitionKey(id));
                       widget = response.Resource;
                   }
                   catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
                   {
                       _logger.LogWarning("Widget with ID {WidgetId} not found for analysis", id);
                       throw new Error(404, $"Widget with ID '{id}' not found");
                   }
   
                   // Create the analysis result
                   var result = new AnalyzeResult
                   {
                       Id = widget.Id,
                       Analysis = $"Weight: {widget.Weight}, Color: {widget.Color}"
                   };
   
                   _logger.LogInformation("Analyzed widget with ID {WidgetId}", id);
                   return result;
               }
               catch (Error)
               {
                   // Rethrow Error exceptions
                   throw;
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error analyzing widget {WidgetId} from Cosmos DB", id);
                   throw new Error(500, "Failed to analyze widget from database");
               }
           }
       }
   }
   

6. ./server/services/CosmosDbInitializer.cs Vytvořte soubor pro ověření v Azure:

   using System;
   using System.Threading;
   using System.Threading.Tasks;
   using Microsoft.Azure.Cosmos;
   using Microsoft.Extensions.Configuration;
   using Microsoft.Extensions.Hosting;
   using Microsoft.Extensions.Logging;
   
   namespace WidgetService.Service
   {
       /// <summary>
       /// Hosted service that initializes Cosmos DB resources on application startup
       /// </summary>
       public class CosmosDbInitializer : IHostedService
       {
           private readonly CosmosClient _cosmosClient;
           private readonly ILogger<CosmosDbInitializer> _logger;
           private readonly IConfiguration _configuration;
           private readonly string _databaseName;
           private readonly string _containerName = "Widgets";
   
           public CosmosDbInitializer(CosmosClient cosmosClient, ILogger<CosmosDbInitializer> logger, IConfiguration configuration)
           {
               _cosmosClient = cosmosClient;
               _logger = logger;
               _configuration = configuration;
               _databaseName = _configuration["CosmosDb:DatabaseName"] ?? "WidgetDb";
           }
   
           public async Task StartAsync(CancellationToken cancellationToken)
           {
               _logger.LogInformation("Ensuring Cosmos DB database and container exist...");
   
               try
               {
                   // Create database if it doesn't exist
                   var databaseResponse = await _cosmosClient.CreateDatabaseIfNotExistsAsync(
                       _databaseName,
                       cancellationToken: cancellationToken);
   
                   _logger.LogInformation("Database {DatabaseName} status: {Status}", _databaseName,
                       databaseResponse.StatusCode == System.Net.HttpStatusCode.Created ? "Created" : "Already exists");
   
                   // Create container if it doesn't exist (using id as partition key)
                   var containerResponse = await databaseResponse.Database.CreateContainerIfNotExistsAsync(
                       new ContainerProperties
                       {
                           Id = _containerName,
                           PartitionKeyPath = "/id"
                       },
                       throughput: 400, // Minimum RU/s
                       cancellationToken: cancellationToken);
   
                   _logger.LogInformation("Container {ContainerName} status: {Status}", _containerName,
                       containerResponse.StatusCode == System.Net.HttpStatusCode.Created ? "Created" : "Already exists");
               }
               catch (Exception ex)
               {
                   _logger.LogError(ex, "Error initializing Cosmos DB");
                   throw;
               }
           }
   
           public Task StopAsync(CancellationToken cancellationToken)
           {
               return Task.CompletedTask;
           }
       }
   }
   

7. ./server/program.cs Aktualizujte rozhraní Cosmos DB tak, aby bylo možné použít uživatelské rozhraní Swagger v produkčním nasazení. Zkopírujte celý soubor:

   // Generated by @typespec/http-server-csharp
   // <auto-generated />
   #nullable enable
   
   using TypeSpec.Helpers;
   using WidgetService.Service;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.AddControllersWithViews(options =>
   {
       options.Filters.Add<HttpServiceExceptionFilter>();
   });
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen();
   
   // Replace original registration with the Cosmos DB one
   CosmosDbRegistration.RegisterCosmosServices(builder);
   
   var app = builder.Build();
   
   // Configure the HTTP request pipeline.
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/Home/Error");
       // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
       app.UseHsts();
   }
   
   // Swagger UI is always available
   app.UseSwagger();
   app.UseSwaggerUI(c =>
   {
       c.DocumentTitle = "TypeSpec Generated OpenAPI Viewer";
       c.SwaggerEndpoint("/openapi.yaml", "TypeSpec Generated OpenAPI Docs");
       c.RoutePrefix = "swagger";
   });
   
   app.UseHttpsRedirection();
   app.UseStaticFiles();
   app.Use(async (context, next) =>
   {
       context.Request.EnableBuffering();
       await next();
   });
   
   app.MapGet("/openapi.yaml", async (HttpContext context) =>
   {
       var externalFilePath = "wwwroot/openapi.yaml"; 
       if (!File.Exists(externalFilePath))
       {
           context.Response.StatusCode = StatusCodes.Status404NotFound;
           await context.Response.WriteAsync("OpenAPI spec not found.");
           return;
       }
       context.Response.ContentType = "application/json";
       await context.Response.SendFileAsync(externalFilePath);
   });
   
   app.UseRouting();
   app.UseAuthorization();
   
   app.MapControllerRoute(
       name: "default",
       pattern: "{controller=Home}/{action=Index}/{id?}");
   
   app.Run();
   

8. Sestavení projektu:

   dotnet build
   

   Projekt se teď kompiluje s integrací Cosmos DB. Vytvoříme skripty nasazení, které vytvoří prostředky Azure a nasadí projekt.

Vytvoření infrastruktury nasazení

Vytvořte soubory potřebné k opakovatelnému nasazení pomocí Azure Developer CLI a šablon Bicep.

1. V kořenovém adresáři projektu TypeSpec vytvořte azure.yaml definiční soubor nasazení a vložte následující zdroj:

   # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
   
   name: azure-typespec-scaffold-dotnet
   metadata:
       template: azd-init@1.14.0
   services:
       api:
           project: ./server
           host: containerapp
           language: dotnet
   pipeline:
     provider: github
   

   Všimněte si, že tato konfigurace odkazuje na vygenerované umístění projektu (./server). Ujistěte se, že ./tspconfig.yaml odpovídá umístění zadanému v ./azure.yamlsouboru .

2. V kořenovém adresáři projektu TypeSpec vytvořte ./infra adresář.

3. ./infra/main.bicepparam Vytvořte soubor a zkopírujte ho následujícím způsobem, abyste definovali parametry, které potřebujeme pro nasazení:

   using './main.bicep'
   
   param environmentName = readEnvironmentVariable('AZURE_ENV_NAME', 'dev')
   param location = readEnvironmentVariable('AZURE_LOCATION', 'eastus2')
   param deploymentUserPrincipalId = readEnvironmentVariable('AZURE_PRINCIPAL_ID', '')
   

   Tento seznam parametrů poskytuje minimální parametry potřebné pro toto nasazení.

4. ./infra/main.bicep Vytvořte soubor a zkopírujte ho následujícím způsobem, abyste definovali prostředky Azure pro zřizování a nasazení:

   metadata description = 'Bicep template for deploying a GitHub App using Azure Container Apps and Azure Container Registry.'
   
   targetScope = 'resourceGroup'
   param serviceName string = 'api'
   var databaseName = 'WidgetDb'
   var containerName = 'Widgets'
   
   @minLength(1)
   @maxLength(64)
   @description('Name of the environment that can be used as part of naming resource convention')
   param environmentName string
   
   @minLength(1)
   @description('Primary location for all resources')
   param location string
   
   @description('Id of the principal to assign database and application roles.')
   param deploymentUserPrincipalId string = ''
   
   var resourceToken = toLower(uniqueString(resourceGroup().id, environmentName, location))
   
   var tags = {
     'azd-env-name': environmentName
     repo: 'https://github.com/typespec'
   }
   
   module managedIdentity 'br/public:avm/res/managed-identity/user-assigned-identity:0.4.1' = {
     name: 'user-assigned-identity'
     params: {
       name: 'identity-${resourceToken}'
       location: location
       tags: tags
     }
   }
   
   module cosmosDb 'br/public:avm/res/document-db/database-account:0.8.1' = {
     name: 'cosmos-db-account'
     params: {
       name: 'cosmos-db-nosql-${resourceToken}'
       location: location
       locations: [
         {
           failoverPriority: 0
           locationName: location
           isZoneRedundant: false
         }
       ]
       tags: tags
       disableKeyBasedMetadataWriteAccess: true
       disableLocalAuth: true
       networkRestrictions: {
         publicNetworkAccess: 'Enabled'
         ipRules: []
         virtualNetworkRules: []
       }
       capabilitiesToAdd: [
         'EnableServerless'
       ]
       sqlRoleDefinitions: [
         {
           name: 'nosql-data-plane-contributor'
           dataAction: [
             'Microsoft.DocumentDB/databaseAccounts/readMetadata'
             'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
             'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
           ]
         }
       ]
       sqlRoleAssignmentsPrincipalIds: union(
         [
           managedIdentity.outputs.principalId
         ],
         !empty(deploymentUserPrincipalId) ? [deploymentUserPrincipalId] : []
       )
       sqlDatabases: [
         {
           name: databaseName
           containers: [
             {
               name: containerName
               paths: [
                 '/id'
               ]
             }
           ]
         }
       ]
     }
   }
   
   module containerRegistry 'br/public:avm/res/container-registry/registry:0.5.1' = {
     name: 'container-registry'
     params: {
       name: 'containerreg${resourceToken}'
       location: location
       tags: tags
       acrAdminUserEnabled: false
       anonymousPullEnabled: true
       publicNetworkAccess: 'Enabled'
       acrSku: 'Standard'
     }
   }
   
   var containerRegistryRole = subscriptionResourceId(
     'Microsoft.Authorization/roleDefinitions',
     '8311e382-0749-4cb8-b61a-304f252e45ec'
   ) 
   
   module registryUserAssignment 'br/public:avm/ptn/authorization/resource-role-assignment:0.1.1' = if (!empty(deploymentUserPrincipalId)) {
     name: 'container-registry-role-assignment-push-user'
     params: {
       principalId: deploymentUserPrincipalId
       resourceId: containerRegistry.outputs.resourceId
       roleDefinitionId: containerRegistryRole
     }
   }
   
   module logAnalyticsWorkspace 'br/public:avm/res/operational-insights/workspace:0.7.0' = {
     name: 'log-analytics-workspace'
     params: {
       name: 'log-analytics-${resourceToken}'
       location: location
       tags: tags
     }
   }
   
   module containerAppsEnvironment 'br/public:avm/res/app/managed-environment:0.8.0' = {
     name: 'container-apps-env'
     params: {
       name: 'container-env-${resourceToken}'
       location: location
       tags: tags
       logAnalyticsWorkspaceResourceId: logAnalyticsWorkspace.outputs.resourceId
       zoneRedundant: false
     }
   }
   
   module containerAppsApp 'br/public:avm/res/app/container-app:0.9.0' = {
     name: 'container-apps-app'
     params: {
       name: 'container-app-${resourceToken}'
       environmentResourceId: containerAppsEnvironment.outputs.resourceId
       location: location
       tags: union(tags, { 'azd-service-name': serviceName })
       ingressTargetPort: 8080
       ingressExternal: true
       ingressTransport: 'auto'
       stickySessionsAffinity: 'sticky'
       scaleMaxReplicas: 1
       scaleMinReplicas: 1
       corsPolicy: {
         allowCredentials: true
         allowedOrigins: [
           '*'
         ]
       }
       managedIdentities: {
         systemAssigned: false
         userAssignedResourceIds: [
           managedIdentity.outputs.resourceId
         ]
       }
       secrets: {
         secureList: [
           {
             name: 'azure-cosmos-db-nosql-endpoint'
             value: cosmosDb.outputs.endpoint
           }
           {
             name: 'user-assigned-managed-identity-client-id'
             value: managedIdentity.outputs.clientId
           }
         ]
       }
       containers: [
         {
           image: 'mcr.microsoft.com/dotnet/samples:aspnetapp-9.0'
           name: serviceName
           resources: {
             cpu: '0.25'
             memory: '.5Gi'
           }
           env: [
             {
               name: 'CONFIGURATION__AZURECOSMOSDB__ENDPOINT'
               secretRef: 'azure-cosmos-db-nosql-endpoint'
             }
             {
               name: 'AZURE_CLIENT_ID'
               secretRef: 'user-assigned-managed-identity-client-id'
             }
           ]
         }
       ]
     }
   }
   
   output CONFIGURATION__AZURECOSMOSDB__ENDPOINT string = cosmosDb.outputs.endpoint
   output CONFIGURATION__AZURECOSMOSDB__DATABASENAME string = databaseName
   output CONFIGURATION__AZURECOSMOSDB__CONTAINERNAME string = containerName
   
   output AZURE_CONTAINER_REGISTRY_ENDPOINT string = containerRegistry.outputs.loginServer
   

   Výstupní proměnné umožňují používat zřízené cloudové prostředky s místním vývojem.

5. Značka containerAppsApp používá proměnnou serviceName (nastavenou na api na začátku souboru) a api zadanou v ./azure.yaml. Toto připojení informuje Azure Developer CLI, kde nasadit projekt .NET do hostitelského prostředku Azure Container Apps.

   ...bicep...
   
   module containerAppsApp 'br/public:avm/res/app/container-app:0.9.0' = {
     name: 'container-apps-app'
     params: {
       name: 'container-app-${resourceToken}'
       environmentResourceId: containerAppsEnvironment.outputs.resourceId
       location: location
       tags: union(tags, { 'azd-service-name': serviceName })                    <--------- `API`
   
   ...bicep..
   

Struktura projektu

Konečná struktura projektu zahrnuje soubory rozhraní API TypeSpec, Express.js server a soubory nasazení Azure:

├── infra
├── tsp-output
├── .gitignore
├── .azure.yaml
├── Dockerfile
├── main.tsp
├── package-lock.json
├── package.json
├── tspconfig.yaml

Area	Soubory/adresáře
TypeSpec	main.tsp, tspconfig.yaml
Express.js server	./tsp-output/server/ (včetně vygenerovaných souborů, jako je controllers/, models/, ServiceProject.csproj)
Nasazení Azure Developer CLI	./azure.yaml,./infra/

Nasazení aplikace do Azure

Tuto aplikaci můžete nasadit do Azure pomocí Azure Container Apps:

1. Ověření v Azure Developer CLI:

   azd auth login
   

2. Nasazení do Azure Container Apps pomocí Azure Developer CLI:

   azd up
   

Použití aplikace v prohlížeči

Po nasazení můžete:

1. Přejděte k uživatelskému rozhraní Swagger a otestujte své rozhraní API na adrese /swagger.
2. Pomocí funkce Vyzkoušet teď v jednotlivých rozhraních API můžete vytvářet, číst, aktualizovat a odstraňovat widgety prostřednictvím rozhraní API.

Rozšiřte svou aplikaci

Teď, když máte celý kompletní proces, pokračujte vytvořením rozhraní API:

• Další informace o jazyku TypeSpec pro přidání dalších rozhraní API a funkcí vrstvy rozhraní API v nástroji ./main.tsp.
• Přidejte další emitory a nakonfigurujte jejich parametry v souboru ./tspconfig.yaml.
• Když do souborů TypeSpec přidáte další funkce, podpořte tyto změny zdrojovým kódem v serverovém projektu.
• Pokračujte v používání ověřování bez hesla s využitím identity Azure.

Vyčistěte zdroje

Po dokončení tohoto rychlého startu můžete odebrat prostředky Azure:

azd down

Nebo skupinu prostředků odstraňte přímo z Azure portalu.

Další kroky

• Dokumentace k TypeSpec
• Dokumentace ke službě Azure Cosmos DB
• Nasazení aplikací Node.js do Azure
• Dokumentace ke službě Azure Container Apps