diff --git a/.github/workflows/build-documentation.yml b/.github/workflows/build-documentation.yml index b40a6a8e8..e6f7c6772 100644 --- a/.github/workflows/build-documentation.yml +++ b/.github/workflows/build-documentation.yml @@ -1,15 +1,25 @@ name: Build Documentation -# repository_dispatch is used to trigger the flow from Npgsql/EFCore.PG via HTTP POST -on: [push, pull_request, repository_dispatch] +on: + push: + branches: [main] + + pull_request: + + # Used to trigger the flow from Npgsql/EFCore.PG via HTTP POST + repository_dispatch: + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +concurrency: + group: "pages" + cancel-in-progress: false jobs: build: runs-on: ubuntu-22.04 - permissions: - contents: write - steps: - name: Checkout repo uses: actions/checkout@v4 @@ -25,14 +35,11 @@ jobs: npm i -g markdownlint-cli markdownlint "conceptual/**/*.md" - - name: Checkout live branch - uses: actions/checkout@v4 + # Setup software + - name: Setup .NET Core + uses: actions/setup-dotnet@v4.0.1 with: - ref: live - path: live - - - name: Clear live docs repo - run: rm -rf live/* + dotnet-version: 7.0.x - name: Checkout Npgsql uses: actions/checkout@v4 @@ -41,13 +48,7 @@ jobs: ref: docs path: Npgsql - # Setup software - - name: Setup .NET Core - uses: actions/setup-dotnet@v4.0.1 - with: - dotnet-version: 7.0.x - - # docfx has issues specifically with analyzer/sourcegen projects; build manually before + # docfx has issues specifically with analyzer/sourcegen projects; build manually before. - name: Build Npgsql run: dotnet build -c Release shell: bash @@ -65,27 +66,29 @@ jobs: shell: bash working-directory: EFCore.PG - # Note: - # Since we use a custom template to override some properties of the docfx default template, when upgrading docfx we should check - # whether the default template of the new docfx version has changes we need to carry over to our modified version. - # You can get the docfx default template via the following command: docfx template export default - # This will put the default template folder into a directory called _exported_templates - name: Get docfx run: dotnet tool install --version 2.77.0 -g docfx - name: Build docs run: docfx --warningsAsErrors - - name: Commit and push - if: (github.event_name == 'push' || github.event_name == 'repository_dispatch') && github.repository == 'npgsql/doc' && github.ref == 'refs/heads/main' - run: | - export GIT_COMMITTER_NAME=$(git show -s --format='%cn') - export GIT_COMMITTER_EMAIL=$(git show -s --format='%ce') - export GIT_AUTHOR_NAME=$(git show -s --format='%an') - export GIT_AUTHOR_EMAIL=$(git show -s --format='%ae') - export COMMIT_HASH=$(git show -s --format='%H') - export SUBJECT=$(git show -s --format='%s') - cd live - git add . - git commit -m "$SUBJECT" -m "Original commit: $COMMIT_HASH" - git push origin HEAD:live + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + needs: build + runs-on: ubuntu-latest + if: github.event_name == 'push' && github.ref_name == 'main' + permissions: + contents: read + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index b2ee2defe..6114fe902 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ obj /EFCore.PG /Npgsql -/live +/_site /_exported_templates diff --git a/conceptual/EF6.PG/index.md b/conceptual/EF6.PG/index.md index d1fd060f9..3e030de59 100644 --- a/conceptual/EF6.PG/index.md +++ b/conceptual/EF6.PG/index.md @@ -1,16 +1,13 @@ ---- -layout: doc -title: Entity Framework 6 ---- +# Entity Framework 6 Npgsql has an Entity Framework 6 provider. You can use it by installing the [EntityFramework6.Npgsql](https://www.nuget.org/packages/EntityFramework6.Npgsql/) nuget. -## Basic Configuration ## +## Basic Configuration Configuration for an Entity Framework application can be specified in a config file (app.config/web.config) or through code. The latter is known as code-based configuration. -### Code-based ### +### Code-based To use Entity Framework with Npgsql, define a class that inherits from `DbConfiguration` in the same assembly as your class inheriting `DbContext`. Ensure that you configure provider services, a provider factory, a default connection factory as shown below: @@ -35,7 +32,7 @@ class NpgSqlConfiguration : DbConfiguration } ``` -### Config file ### +### Config file When installing `EntityFramework6.Npgsql` nuget package, the relevant sections in `App.config` / `Web.config` are usually automatically updated. You typically only have to add your `connectionString` with the correct `providerName`. @@ -59,7 +56,7 @@ When installing `EntityFramework6.Npgsql` nuget package, the relevant sections i ``` -## Guid Support ## +## Guid Support Npgsql EF migrations support uses `uuid_generate_v4()` function to generate guids. In order to have access to this function, you have to install the extension uuid-ossp through the following command: @@ -78,7 +75,7 @@ If the database is being created by Npgsql Migrations, you will need to [run the `create extension` command in the `template1` database](http://stackoverflow.com/a/11584751). This way, when the new database is created, the extension will be installed already. -## Optimistic Concurrency ## +## Optimistic Concurrency EntityFramework supports [optimistic concurrency](https://docs.microsoft.com/en-us/aspnet/mvc/overview/getting-started/getting-started-with-ef-using-mvc/handling-concurrency-with-the-entity-framework-in-an-asp-net-mvc-application), through the [system column `xmin`](https://www.postgresql.org/docs/current/ddl-system-columns.html). To use this column as the concurrency token, some [customization is needed](https://github.com/npgsql/EntityFramework6.Npgsql/issues/8). The following code will setup `Department.Version` to map to `xmin`, while the `SqlGenerator` will generate `CREATE/ALTER TABLE` statements omitting system columns. @@ -126,7 +123,7 @@ public class SqlGenerator : NpgsqlMigrationSqlGenerator } ``` -## Template Database ## +## Template Database When the Entity Framework 6 provider creates a database, it issues a simple `CREATE DATABASE` command. In PostgreSQL, this implicitly uses `template1` as the template - anything existing in `template1` will @@ -134,7 +131,7 @@ be copied to your new database. If you wish to change the database used as a tem the `EF Template Database` connection string parameter. For more info see the [PostgreSQL docs](https://www.postgresql.org/docs/current/static/sql-createdatabase.html). -## Customizing DataReader Behavior ## +## Customizing DataReader Behavior You can use [an Entity Framework 6 IDbCommandInterceptor](https://msdn.microsoft.com/library/dn469464(v=vs.113).aspx) to wrap the `DataReader` instance returned by Npgsql when Entity Framework executes queries. This is possible using a ```DbConfiguration``` class. diff --git a/docfx.json b/docfx.json index caceb9687..07aa0337e 100644 --- a/docfx.json +++ b/docfx.json @@ -1,7 +1,9 @@ { - "metadata": [ + "metadata": + [ { - "src": [ + "src": + [ { "files": [ "src/Npgsql/Npgsql.csproj" ], "exclude": [ "src/MSI/**", "src/VSIX/**", "**/bin/**", "**/obj/**" ], @@ -9,12 +11,14 @@ } ], "dest": "obj/api/Npgsql", - "properties": { + "properties": + { "TargetFramework": "net8.0" } }, { - "src": [ + "src": + [ { "files": [ "src/**/*.csproj" ], "exclude": [ "**/bin/**", "**/obj/**", "Properties/NpgsqlStrings.*" ], @@ -22,17 +26,21 @@ } ], "dest": "obj/api/EFCore.PG", - "properties": { + "properties": + { "TargetFramework": "net8.0" } } ], - "build": { - "template": [ + "build": + { + "template": + [ "default", "modern" ], - "content": [ + "content": + [ { "files": [ "**/*.yml" ], "src": "obj/api/Npgsql", @@ -62,7 +70,8 @@ "files": [ "*.md", "dev/**.md", "toc.yml" ] } ], - "resource": [ + "resource": + [ { "files": [ "img/**", "styles/**", "CNAME" ] }, @@ -71,6 +80,7 @@ "src": "favicons" } ], + "output": "_site", "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ], "globalMetadata": { "_appTitle": "Npgsql Documentation", @@ -92,7 +102,6 @@ "branch": "stable" } } - }, - "dest" : "live" + } } }