diff --git a/Beef.sln b/Beef.sln index 85c6a26cf..063cbf982 100644 --- a/Beef.sln +++ b/Beef.sln @@ -177,6 +177,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{FDBFD331-A docs\Layer-ServiceInterface.md = docs\Layer-ServiceInterface.md docs\Reference-Data.md = docs\Reference-Data.md docs\Sample-Cosmos-GettingStarted.md = docs\Sample-Cosmos-GettingStarted.md + docs\Sample-Postgres-EF-GettingStarted.md = docs\Sample-Postgres-EF-GettingStarted.md docs\Sample-SqlServer-EF-GettingStarted.md = docs\Sample-SqlServer-EF-GettingStarted.md docs\Sample-SqlServer-StoredProcs-GettingStarted.md = docs\Sample-SqlServer-StoredProcs-GettingStarted.md docs\Solution-Structure.md = docs\Solution-Structure.md @@ -201,7 +202,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyEf.Hr.Security.Subscripti EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MyEf.Hr.Security.Test", "samples\MyEf.Hr\MyEf.Hr.Security.Test\MyEf.Hr.Security.Test.csproj", "{7AE6E1D4-8621-4FC5-8A1F-448FA70DB257}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Beef.Database.Postgres", "tools\Beef.Database.Postgres\Beef.Database.Postgres.csproj", "{1FC9C576-99C9-44B2-AD86-9B8A0C76D79E}" +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Beef.Database.Postgres", "tools\Beef.Database.Postgres\Beef.Database.Postgres.csproj", "{1FC9C576-99C9-44B2-AD86-9B8A0C76D79E}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution diff --git a/README.md b/README.md index 0837db94a..27c92f67c 100644 --- a/README.md +++ b/README.md @@ -263,9 +263,10 @@ _Beef_ is open source under the [MIT license](./LICENSE) and is free for commerc To start using _Beef_ you do not need to clone or fork the repo; you just need to create a solution with the underlying projects using the prescribed [solution structure](./docs/Solution-Structure.md), including referencing the appropriate [NuGet packages](#Framework). To accelerate this a .NET Core [template capability](./templates/Beef.Template.Solution/README.md) is provided to enable you to get up and running in minutes. See the following for example end-to-end solution/project creation; each demonstrating the same API functionality leveraging different data sources to accomplish: -- [Cosmos sample](./docs/Sample-Cosmos-GettingStarted.md) -- [SQL Server Stored Procedures sample](./docs/Sample-SqlServer-StoredProcs-GettingStarted.md) -- [SQL Server Entity Framework sample](./docs/Sample-SqlServer-EF-GettingStarted.md) +- [_Cosmos_ sample](./docs/Sample-Cosmos-GettingStarted.md) +- [_PostgreSQL_ Entity Framework sample](./docs/Sample-Postgres-EF-GettingStarted.md) +- [_SQL Server_ Entity Framework sample](./docs/Sample-SqlServer-EF-GettingStarted.md) +- [_SQL Server_ Stored Procedures sample](./docs/Sample-SqlServer-StoredProcs-GettingStarted.md) Otherwise, follow along with the following sample tutorials that will provide a more in-depth walkthrough solving a defined functional problem: diff --git a/docs/Sample-Postgres-EF-GettingStarted.md b/docs/Sample-Postgres-EF-GettingStarted.md new file mode 100644 index 000000000..e1919e70c --- /dev/null +++ b/docs/Sample-Postgres-EF-GettingStarted.md @@ -0,0 +1,111 @@ +# Getting started + +This tutorial will demonstrate how to get a .NET Solution using _Beef_ created on your machine connecting to [PostgreSQL](https://www.postgresql.org/) using [Entity Framework](https://docs.microsoft.com/en-us/ef/core/) for data access. A pre-configured soluion will be created to enable, and demonstrate, the key end-to-end capabilities. + +
+ +## Prerequisites + +The following need to be installed locally for the sample to run: + +- Download and install the **Microsoft SQL Server Developer edition**: https://www.microsoft.com/en-us/sql-server/sql-server-downloads + +It is recommended that the following is installed to simplify the opening of a command line from Visual Studio: +- Download and install the **Open Command Line** extension for Visual Studio: http://vsixgallery.com/extension/f4ab1e64-5d35-4f06-bad9-bf414f4b3bbb/. The use of `Alt+Space` will open a command line (or PowerShell) in the directory of the open file. + +
+ +## Beef Template Solution + +The [`Beef.Template.Solution`](../templates/Beef.Template.Solution/README.md) needs to be installed so that it can be used to easily create the required [solution structure](./Solution-Structure.md). + +Install (or update) the latest template from the public [NuGet](https://www.nuget.org/packages/Beef.Template.Solution/) repository using the [`dotnet new install`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new-install) or `dotnet new -i` ([deprecated](https://github.com/dotnet/docs/issues/32195)) command as follows (or alternatively specify the required version): + +``` +dotnet new install beef.template.solution --nuget-source https://api.nuget.org/v3/index.json +dotnet new install beef.template.solution::5.0.1.preview7 --nuget-source https://api.nuget.org/v3/index.json +``` + +
+ +## Create solution + +To create the _Solution_ you must first be in the directory that you intend to create the artefacts within. The _beef_ template requires the `company` and `appname`; which is also the recommended directory name (it will also represent the .NET namespace). For this tutorial we will also choose the `Postgres` data source. + +``` +mkdir Foo.Bar +cd Foo.Bar +dotnet new beef --company Foo --appname Bar --datasource Postgres +``` + +The solution should now have been created; and the file system should look like the following: + +``` +└── Foo.Bar + └── Foo.Bar.Api # API end-point and operations + └── Foo.Bar.Business # Core business logic components + └── Foo.Bar.CodeGen # Entity and Reference Data code generation console + └── Foo.Bar.Database # Database setup and configuration + └── Foo.Bar.Common # Common / shared components + └── Foo.Bar.Test # Unit and intra-integration tests + └── Foo.Bar.sln # Solution file that references all above projects +``` + +
+ +## Code-generation + +The solution has been created with a sample `Person` entity defined and related [reference data](./Reference-Data.md) to demonstrate the code generation configuration. There are other `Person` related classes within the solution to demonstrate the corresponding non-generated interactions, as well as the [intra-integration testing](../tools/Beef.Test.NUnit/README.md). + +The [code-generation](../tools/Beef.CodeGen.Core/README.md) will reference the following configuration within the `Foo.Bar.CodeGen` directory: +- `entity.beef-5.yaml` - contains the entity(s) configuration. +- `refdata.beef-5.yaml` - contains the reference data configuration. + +Generate the configured entities and reference data by performing the following: + +``` +cd Foo.Bar.CodeGen +dotnet run all +``` + +This will build and run the `Foo.Bar.CodeGen` console; the outcome of the code generation will be logged to the console showing what was added or updated. + +
+ +## Database generation and configuration + +The solution has been created with the sample `Person` table defined and related reference data tables, migration scripts to create the database objects. + +The [database generation](../tools/Beef.Database.Core/README.md) will reference the following configuration within the `Foo.Bar.Database` directory: +- `database.beef-5.yaml` - contains the table(s) and related C# model configuration. + +Generate the configured tables and C# models by performing the following: + +``` +cd Foo.Bar.Database +dotnet run all +``` + +This will build and run the `Foo.Bar.Database` console; the outcome of the code generation and database setup/configuration will be logged to the console showing what was added or updated. + +
+ +## Testing + +To verify that the generated APIs function as expected an example set of tests has been created to exercise the GET/PUT/POST/PATCH/DELETE operations: + +``` +cd ..\Foo.Bar.Test +dotnet test Foo.Bar.Test.csproj +``` + +
+ +## Visual Studio + +Open the solution within Visual Studio: + +``` +cd .. +Foo.Bar.sln +``` \ No newline at end of file diff --git a/templates/Beef.Template.Solution/README.md b/templates/Beef.Template.Solution/README.md index ade335ce3..40dc68355 100644 --- a/templates/Beef.Template.Solution/README.md +++ b/templates/Beef.Template.Solution/README.md @@ -124,6 +124,7 @@ For more information see: [data-generation](../../tools/Beef.Database.Core/READM ## Samples See the following samples for end-to-end usage: -- [SQL Server Entity Framework sample](../../docs/Sample-SqlServer-EF-GettingStarted.md) -- [SQL Server Stored Procedure sample](../../docs/Sample-SqlServer-StoredProcs-GettingStarted.md) -- [Cosmos sample](../../docs/Sample-Cosmos-GettingStarted.md) +- [_Cosmos_ sample](../../docs/Sample-Cosmos-GettingStarted.md) +- [_PostgreSQL_ Entity Framework sample](../../docs/Sample-Postgres-EF-GettingStarted.md) +- [_SQL Server_ Entity Framework sample](../../docs/Sample-SqlServer-EF-GettingStarted.md) +- [_SQL Server_ Stored Procedure sample](../../docs/Sample-SqlServer-StoredProcs-GettingStarted.md) \ No newline at end of file diff --git a/tools/Beef.CodeGen.Core/README.md b/tools/Beef.CodeGen.Core/README.md index 74748c229..12e327db7 100644 --- a/tools/Beef.CodeGen.Core/README.md +++ b/tools/Beef.CodeGen.Core/README.md @@ -160,13 +160,13 @@ Command | Description Additionally, there are a number of command line options that can be used. ``` -Business Entity Execution Framework (Beef) Code Generator tool. +Beef.CodeGen.Core Code Generation Tool. Usage: Beef.CodeGen.Core [options] Arguments: command Execution command type. - Allowed values are: Entity, Database, RefData, DataModel, All. + Allowed values are: Entity, Database, RefData, DataModel, All, Clean, Count. Options: -?|-h|--help Show help information. @@ -179,6 +179,13 @@ Options: -cv|--connection-varname Database connection string environment variable name. -enc|--expect-no-changes Indicates to expect _no_ changes in the artefact output (e.g. error within build pipeline). -sim|--simulation Indicates whether the code-generation is a simulation (i.e. does not create/update any artefacts). + +Extended commands and argument(s): + clean Cleans (removes) all related directories named 'Generated'. + - Use --param exclude=name[,name] to exclude named directory(s) from the clean. + + count Counts and reports the number of files and lines (All and Generated) within all related directories. + - Use --param exclude=name[,name] to exclude named directory(s) from the count. ```
diff --git a/tools/Beef.Database.Core/README.md b/tools/Beef.Database.Core/README.md index a6b11618a..c409eda25 100644 --- a/tools/Beef.Database.Core/README.md +++ b/tools/Beef.Database.Core/README.md @@ -10,8 +10,9 @@ The primary/core capabilities are enabled by [`DbEx`](https://github.com/Avanade Depending on the underlying database provider specific capabilities are enabled; see: -- [SQL Server](../Beef.Database.SqlServer) - [MySQL](../Beef.Database.MySql) +- [Postgres](../Beef.Database.Postgres) +- [SQL Server](../Beef.Database.SqlServer)