About Generated Projects
This package is highly experimental and may be subject to breaking changes and bugs. Please expect that your code may need to be updated as this package evolves, and please report any issues you encounter.
The code layout inside the âgeneratedâ folder is as follows:
-
generated
- controllers: A set of ASP.Net core MVC controllers representing the operations in the spec, one for each interface or namespace with operations
- lib: A set of library files used in implementing generated models and controllers
- models: A set of models, each serving one of two distinct purposes:
- Request/Response Models: Represent the data used in requests and responses.
- Exception Models: Represent errors. These models inherit from
HttpServiceException
and are designed to encapsulate error details, making them suitable for throwing and handling exceptions.
- operations: A set of interfaces called by the controllers, that should be implemented with the business logic for each operation.
You should recompile whenever you make changes in your TypeSpec and these files will be replaced inline to reflect the spec changes, without changing any of your hand-written implementation in the project.
Scaffolding
Section titled âScaffoldingâIf you use the scaffolding cli (hscs-scaffold) or use the --emit-mocks "mocks-and-project-files"
option on compilation, a fully-functional .Net 9 project will be created with mock implementations of your business
logic, ready to compile and run.
The following additional files will be generated. It is expected that you will edit or replace these
files as you implement your service, so you should only regenerate them when needed.
To protect from inadvertently changing any edits you may have made to these files,
these files will be overwritten by the emitter unless you specify the --overwrite
option.
-
ServiceProject.csproj: The project file
-
Program.cs: Entry point that sets up the app
-
appSettings.Development.json: Configuration settings for the development environment
-
appSettings.json: Configuration settings for the production environment
-
Properties
- launchSettings.json: Launch configurations for the service (including local ports)
-
mocks: Simple implementations of business logic interfaces that return simple responses. this allows testing your service out before writing any implementation code.
- MockRegistration.cs: Called from the Program.cs startup, registers each of the business logic implementations in the dependency injection container.
- IInitializer.cs: Interface used in the mocks to create responses.
- Initializer.cs: Implementation of the interface to create mock responses.
Generating a Project and Mock Implementations using tsp compile
Section titled âGenerating a Project and Mock Implementations using tsp compileâIf you downloaded the tsp
standalone component and you donât have node
and npm
installed, you will not be able to use the hscs-scaffold
command to create an ASP.Net project. Instead, you can use compiler options, for example, the following command will create a new project using the TypeSpec in the current directory, enabling SwaggerUI, and overwriting any existing mocks or project files:
tsp compile . --emit @typespec/http-server-csharp --emit @typespec/openapi3 --option @typespec/http-server-csharp.emit-mocks=emit-mocks-and-project-files --option @typespec/http-server-csharp.use-swaggerui=true --option @typespec/http-server-csharp.overwrite=true
Once you have customized the project, you can generate new mocks for any new APIs while leaving existing implementations unchanged using:
tsp compile . --emit @typespec/http-server-csharp --option @typespec/http-server-csharp.emit-mocks=mocks-only
SwaggerUI
Section titled âSwaggerUIâIf you include the @typespec/openapi3
emitter in your typespec project, you can include a
SwaggerUI endpoint in the generated service using the --use-swaggerui
option. This endpoint
provides a visual representation of operations and provides a web GUI client connected to the service that you can use right away to try out service operations.
How Components Work Together
Section titled âHow Components Work TogetherâControllers
Section titled âControllersâThe generated controllers automatically listen at the routes you specified in TypeSpec. Controllers perform validation of input requests, call your implementation of business logic interfaces to perform the operation, and return the appropriate Http response.
Business Logic Interfaces
Section titled âBusiness Logic InterfacesâYou must implement business loginc interfaces to perform the work of each operation. There is one
business logic interface for each interface
type in your spec, or for each namespace that contain operations. Business logic can assume that input types meet the constraints specified in TypeSpec and are responsible for returning the response type for the operation.
You can use the --emit-mocks
option to emit mock implementations of your business logic, these mocks demonstrate a simple implementation that returns responses that match the response type in TypeSpec. They also show how to use IHttpContextAccessor
to access additional details of the Http request and response.
Discovery using the ASP.Net Core Dependency Injection Container
Section titled âDiscovery using the ASP.Net Core Dependency Injection ContainerâThe Controllers find your business logic implementation through the ASP.Net dependency injection container. At server start, you register each of your implementations with the dependency injection container and they will automatically be instantiated and used by the controllers.
If you use the --emit-mocks
option, sample code registering mock implementations is emitted to mocks/MockRegistration.cs
.
Model classes represent the data passed in Http requests and response and the data that passes from the front end controllers to your business logic.
Models are partial, so you can add additional members for internal usage as needed by putting a partial class definition with additional members outside the generated
folder in your project.
Next Steps
Section titled âNext StepsâAfter successful generation, you should:
- Use the SwaggerUI endpoint to test out the running service
- Implement the business logic interfaces for your operations
- Update MockRegistration.cs, or register each of your interfaces as part of application startup
- Update configuration to suit your needs