- Install the GitHub CLI commands
- Install the CLI tools for Entity Framework Core
- Install .Net 7.0 (Get .NET 7 Preview)
- Install the the extension from the Visual Studio Marketplace
To work with the Code Generator, you will need to add some config (or you will need to complete this every time).
In Visual Studio, go to TOOLS > OPTIONS > Standardly and complete
- Display Name
- Your GitHub Username
- Default Base Branch Name (By default GitHub uses main)
(If yours is master, you can change this by running the following command git config --global init.defaultBranch main)
Copyright and License are set to MIT License by default. You can change this if you want smething else. (This will only be applied to new projects via the .editorconfig file and will not override the license file or copyright for other projects.)
3.1 Open Visual Studio and choose "Create a new project"
3.2 In the Create a new project window, search for "Standardly" and select the Standardly - Multi Project Template.
3.3 Type in the name you would like for the solution name. (Keep it in a namespace format i.e. no spaces)
3.4 Check the box for "Place solution and project in the same directory" otherwise the multi-project teplate will another unneccesary folder.
3.5 Click on Create
You will now see skeleton projects for the following:
- $solution name%.Api
- $solution name%.Api.Infrastructure.Build
- $solution name%.Api.Infrastructure.Provision
- $solution name%.Api.Tests.Acceptance
- $solution name%.Api.Tests.Unit
(By design there will NOT be any folders / placeholders for things that are not there yet i.e. Services. Theses will be later via the code generation tool.)
3.6 Add your project to GitHub as the Standardly will commit code for the various steps i.e. with services the failing and then the passing tests followed by a Pull Request when all tasks are done.
3.4 We are now ready to start generating the code. You can get to the Code Generator by either selecting a project in Solution Explorer, right click > Add > Standardly Code Generator OR once a project is selected, using CTRL + SHIFT + F4 to bring up the Code Generator.
Now that the Code Generator is open we want to generate code for $solution name%.Api.Infrastructure.Build project 1st so we can build agent can validate future pulll requests.
3.5.1 In the "Search for templates" textbox type "build". It will filter to "INFRA: Setup Infrastructure Build Project" OR select "INFRA: Setup Infrastructure Build Project" from the Template Drop Down.
3.5.2 As we have done the config already there is no other things left to complete other than checking the boxes under "Legal Stuff". (If you have not done the config, you can manually fill that in on the Configuration tab OR alter anything if you do not want to use the default items)
3.5.3 Once all the mandatory items is completed, click on the "Generate Code From Template" button. This will add the code to the Program.cs file in the build project, commit the code to GitHub and create a Pull Request.
You will then see a console box appear and disappear as scripts are executed and once done, you will see some tasks/actions for things that may need doing that are not automated.
3.5.6 Close the form
3.5.7 Open GitHub and review the Pull Request.
- You will notice that GitHub are aware of the new yaml file
github/workflows/dotnet.ymland that the agent is currently checking the build. - If anything needs amending, you can add your commits to this branch, otherwise if you are satisfied the code can be merged.
3.6.1. Next we will do the Logging Broker, so back in Visual Studio, press CTRL + SHIFT + F4 to bring up the Code Generator.
3.6.2. Find the Logging Broker either via search or the Template Drop Down
3.6.3. Check the boxes under "Legal Stuff" and click on the "Generate Code From Template" button.
3.6.4. Once done, you will see the tasks / action messages again as before and this time we have one manual task to complete, so lets do that now...
-
Close the form
-
You will notice that you are currently in the
users/%GitHub Username%/brokers-loggers-logcriticalbranch. So navigate to Startup.cs and add the DI registration for LoggingBroker =>services.AddTransient<ILoggingBroker, LoggingBroker>();
3.6.5 Commit and push this change
3.6.6 Head over to GitHub now to review the Pull Requests in order. (If needed, you can add further commits to any of the branches if needed)
- You will notice that when you get to pull request "BROKERS: Logging - Log Critical", that the CODE RUB is in the COMMIT history
3.7.1. Next we will do the DateTime Broker, so back in Visual Studio, press CTRL + SHIFT + F4 to bring up the Code Generator.
3.7.2. Find the DateTime Broker either via search or the Template Drop Down
3.7.3. Check the boxes under "Legal Stuff" and click on the "Generate Code From Template" button.
3.7.4. Once done, you will see the tasks / action messages again as before and this time we have do the DI registartion for the DateTimeBroker...
- Close the form
- Navigate to Startup.cs and add the DI registration for DateBroker =>
services.AddTransient<IDateTimeBroker, DateTimeBroker>();
3.7.5 Commit and push this change
3.7.6 Head over to GitHub now to review the Pull Requests in order. (If needed, you can add further commits to any of the branches if needed)
3.8.1. Next we will do a Storage Broker, so back in Visual Studio, press CTRL + SHIFT + F4 to bring up the Code Generator.
3.8.2. Find the Storage Broker either via search or the Template Drop Down
3.8.3. The Storage Broker is the first one that we encounter that does not have a reserved name, so this time we will be allowed to generate a broker for a specific model and you will notice that "Model Singular Name" and "Model Plural Name" is now required.
3.8.4 Lets use "Student" and "Students" for the singular and plural names
3.8.5 Once done, you will see the tasks / action messages again. This time we have no DI registartion as the broker was pre-configured in the multi-project template, but we do however have some other manual tasks to complete.
Looking at the branches we see the following on GitHub:
3.8.6 BROKERS: Storage Broker
- This pull request will create IStorageBroker.cs, StorageBroker.cs if it does not exist. (in our case it is already present and will not be generated)
- It will generate the initial migration, BUT only if the two files above had to be created.
- It will install any required NuGet packages i.e.
Microsoft.EntityFrameworkCore.SqlServer
Review the pull request, add any commits as required and merge this PR.
3.8.7 DATA: Student Model
- As we used Student, we see a new file under Models\Students\Student.cs
- This is a minimal model containing ONLY: Id, CreatedByUserId, CreatedDate, UpdatedByUserId and UpdatedDate.
3.8.7.1 In Visual Studio, switch to branch users/%GitHub Username%/data-students-model and navigate to Models\Students\Student.cs
3.7.7.2 Now we need to update the Student model to contain all the properties that we require for the student. It could look something like this:
public class Student : IAuditable
{
public Guid Id { get; set; }
public string UserId { get; set; }
public string IdentityNumber { get; set; }
public string FirstName { get; set; }
public string MiddleName { get; set; }
public string LastName { get; set; }
public DateTimeOffset BirthDate { get; set; }
public Guid CreatedByUserId { get; set; }
public DateTimeOffset CreatedDate { get; set; }
public Guid UpdatedByUserId { get; set; }
public DateTimeOffset UpdatedDate { get; set; }
}
3.8.7.3 Submit a CODE RUB for the model change and do a commit and push.
3.8.7.1 Head over to GitHub and you will see the build action is running. Review the change and if the build is fine do the merge.
3.8.8 BROKERS: Storage - Insert Student
3.8.8.1 Open the local branch users/%GitHub Username%/brokers-students-insert
3.8.8.2 Merge the local branch users/%GitHub Username%/data-students-model into this branch (users/%GitHub Username%/brokers-students-insert) so that we can see the updated model.
3.8.8.3 First lets register the configuration. Open StorageBroker.cs and add AddStudentConfigurations(modelBuilder); to protected override void OnModelCreating(ModelBuilder modelBuilder)
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
AddStudentConfigurations(modelBuilder);
base.OnModelCreating(modelBuilder);
}
3.8.8.4 Next open StorageBroker.Students.Configurations.cs and add all the fluent configuration that you may require. The change we need to do here can either be not required or a lot depending on the model requirements. This could be something like custom column mappings, navigation properties, unique contstraints etc. For this example I will add a unique constraint.
public partial class StorageBroker
{
private static void AddStudentConfigurations(ModelBuilder modelBuilder)
{
modelBuilder.Entity<Student>()
.HasIndex(student => student.UserId)
.IsUnique();
modelBuilder.Entity<Student>()
.HasIndex(student => student.IdentityNumber)
.IsUnique();
}
}
3.8.8.5 Regardles of whether you added configiration or not, we will need to create a migration file for the Student model. You can add this by completing one of these two commands:
- .Net Core CLI:
dotnet ef migrations add AddStudentModel - Visual Studio:
Add-Migration AddStudentModel
3.8.8.6 Commit and push these changes
3.8.8.7 Head over to GitHub, review the PR and merge if all is OK and no other commits required.
3.8.8.8 Review and merge the remaining PR's and resolve any conflicts if needed.
3.9.1. Next we will do a Foundation, so back in Visual Studio, press CTRL + SHIFT + F4 to bring up the Code Generator.
3.9.2. Find the Foundation Service either via search or the Template Drop Down
3.9.3. The Foundation Service is the second one that we encounter that does not have a reserved name, so this time we will be allowed to generate a service for a specific model and you will notice that "Model Singular Name" and "Model Plural Name" is required again.
3.9.4. We will use "Student" and "Students" for the singular and plural names as we have a broker and model in place already.
3.9.5. In this step, I will change show another way to generate code. Up until now, the there was no code dependencies, so lets pretend you are contributing to a project where you are not a contributor, but you have submitted your PR for review. You are waiting for the review, but you have time and want to press on with work. As you PR is not merged yet, you can change the "Base From" text box to the branch that your code will depend on. In this case the last branch we submitted as a PR was users/%GitHub Username%/brokers-students-delete. So we wil base our new branch on that.
3.9.6. Check the boxes under Legal Stuff and generate the Foundation Service.
3.9.7 Once done, you will see the tasks / action messages again. This time we have to add the DI registartion for the StudentService, so lets do that in Startup.cs and do CODE RUB commit for this.
private static void AddServices(IServiceCollection services)
{
services.AddTransient<IStudentService, StudentService>();
}
3.9.8 You will also remember that we added some extra properties to the Student.cs file and one of our manual actions. We will need to address that if needed for our validation, so let open up StudentServiceTests.Validations.Add.cs and add validation for that.
3.9.9 We now have a failing test, so we can do a commit for ShouldThrowValidationExceptionOnAddIfStudentIsInvalidAndLogItAsync -> FAIL
3.9.10 We no need to make the test pass, so lets add the validation rules for UserId, IdentityNumber, FirstName, LastName in StudentService.Validations.cs ValidateStudentOnAdd
We will also need a new rule so we will need to add
private static dynamic IsInvalid(string text) => new
{
Condition = String.IsNullOrWhiteSpace(text),
Message = "Text is required"
};
3.9.11 The tests now pass, so we can commit ShouldThrowValidationExceptionOnAddIfStudentIsInvalidAndLogItAsync -> PASS
3.9.12 Repeat these steps adding the same validation rules to StudentServiceTests.Validations.Modify.cs and the modify method in StudentService.Validations.cs ValidateStudentOnModify
3.9.13 Make sure all the test pass and do a commit and push
3.9.14 Head over to GitHub, review and merge the PR's
3.10.1. Next we will do the Student Controller, so back in Visual Studio, press CTRL + SHIFT + F4 to bring up the Code Generator.
3.10.2. Find Controllers either via search or the Template Drop Down
3.10.3 Use Student and Students for the singular and plural names.
3.10.4. Check the boxes under "Legal Stuff" and click on the "Generate Code From Template" button.
3.10.5. Once done, you will see the tasks / action messages again as before. Controllers is already registers, so no manual changes to the code.
3.10.6 We however need to do a little work on the PR's. For each PR, we need to show that the exposer is working. Use Swagger to show a success outcome, screenshot and attach it to the PR. Then use Swagger to show how exceptions is handled and attach the screenshots as well to the respective PR's.
I hope to have the templates done for this very soon
- Cosmos Storage Broker
- Event Services
- Front-End templates for Blazor starting with API Brokers and Services
- Front-End templates for React
- Use the Discussion feature to leave comments / suggestions. Any feedback would be greatly appreciated.
- If you have spotted any bugs, please log an issue.
- If you found this useful and would like to contribute, you are very welcome to submit pull requests for bugs or new features.