From 735d4baa49813da331ac0202e7b16871cfec4bec Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Fri, 20 Sep 2024 14:47:34 +0200 Subject: [PATCH] Bump docfx to 2.77.0 and adjust config --- .github/workflows/build-documentation.yml | 26 +++++++++++++++++------ conceptual/EFCore.PG/index.md | 2 +- conceptual/EFCore.PG/release-notes/8.0.md | 6 +++--- conceptual/EFCore.PG/release-notes/9.0.md | 4 ++-- conceptual/Npgsql/release-notes/4.0.md | 2 +- conceptual/Npgsql/release-notes/8.0.md | 12 +++++------ conceptual/Npgsql/security.md | 4 ++-- conceptual/Npgsql/types/json.md | 2 +- docfx.json | 20 ++++++++--------- 9 files changed, 45 insertions(+), 33 deletions(-) diff --git a/.github/workflows/build-documentation.yml b/.github/workflows/build-documentation.yml index b9da1f6a..b40a6a8e 100644 --- a/.github/workflows/build-documentation.yml +++ b/.github/workflows/build-documentation.yml @@ -30,6 +30,7 @@ jobs: with: ref: live path: live + - name: Clear live docs repo run: rm -rf live/* @@ -40,6 +41,18 @@ 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 + - name: Build Npgsql + run: dotnet build -c Release + shell: bash + working-directory: Npgsql + - name: Checkout EFCore.PG uses: actions/checkout@v4 with: @@ -47,11 +60,10 @@ jobs: ref: docs path: EFCore.PG - # Setup software - - name: Setup .NET Core - uses: actions/setup-dotnet@v4.0.1 - with: - dotnet-version: 7.0.x + - name: Build EFCore.PG + run: dotnet build -c Release + 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 @@ -59,10 +71,10 @@ jobs: # 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.61.0 -g docfx + run: dotnet tool install --version 2.77.0 -g docfx - name: Build docs - run: docfx + 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' diff --git a/conceptual/EFCore.PG/index.md b/conceptual/EFCore.PG/index.md index c9699882..475bf4b2 100644 --- a/conceptual/EFCore.PG/index.md +++ b/conceptual/EFCore.PG/index.md @@ -133,7 +133,7 @@ builder.Services.AddDbContextPool(opt => o => o.ConfigureDataSource(dataSourceBuilder => dataSourceBuilder.UseClientCertificate(certificate)))); ``` -`ConfigureDataSource()` provides access to a lower-level [`NpgsqlDataSourceBuilder`](../doc/basic-usage.html#data-source) which you can use to configure all aspects of the Npgsql ADO.NET provider. +`ConfigureDataSource()` provides access to a lower-level [`NpgsqlDataSourceBuilder`](../Npgsql/basic-usage.md#data-source) which you can use to configure all aspects of the Npgsql ADO.NET provider. > [!WARNING] > The EF provider internally creates an NpgsqlDataSource and uses that; for most configuration (e.g. connection string), the provider knows to switch between NpgsqlDataSources automatically. diff --git a/conceptual/EFCore.PG/release-notes/8.0.md b/conceptual/EFCore.PG/release-notes/8.0.md index 596457b3..56c55f96 100644 --- a/conceptual/EFCore.PG/release-notes/8.0.md +++ b/conceptual/EFCore.PG/release-notes/8.0.md @@ -189,9 +189,9 @@ Because of the NativeAOT and trimming work done for Npgsql 8.0 ([release notes]( PostgreSQL type | Default .NET type ---------------------------------------- | -------------------------- -JSON POCO mapping, JsonNode and subtypes | -Unmapped enums, ranges, multiranges | -Read PostgreSQL records as .NET tuples | +JSON POCO mapping, JsonNode and subtypes | +Unmapped enums, ranges, multiranges | +Read PostgreSQL records as .NET tuples | Existing code using the above features will start throwing exceptions after upgrading to version 8.0 of the EF Core provider; the exceptions provide explicit guidance on how to add the opt-ins. diff --git a/conceptual/EFCore.PG/release-notes/9.0.md b/conceptual/EFCore.PG/release-notes/9.0.md index 3df0095d..09076c1e 100644 --- a/conceptual/EFCore.PG/release-notes/9.0.md +++ b/conceptual/EFCore.PG/release-notes/9.0.md @@ -9,7 +9,7 @@ Npgsql.EntityFrameworkCore.PostgreSQL version 9.0 is under development; previews The Npgsql EF provider is built on top of the lower-level Npgsql ADO.NET provider; the configuration interface between these two layers was less than ideal, and configuration been more difficult than it should have been. For version 9.0, the configuration experience has been considerably improved. -Since version 7, the Npgsql ADO.NET provider has been moving to [NpgsqlDataSource](../../doc/basic-usage.html#data-source) as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to `UseNpgsql()`; but this required that the user separately configure a data source and manage it. In addition, features such as plugins and enums require support from both the EF and ADO.NET layers, forcing users to perform multiple setup actions at the different layers. +Since version 7, the Npgsql ADO.NET provider has been moving to [NpgsqlDataSource](../../Npgsql/basic-usage.md#data-source) as the preferred way of configuration connections and obtaining them. At the EF level, it has been possible to pass an NpgsqlDataSource instance to `UseNpgsql()`; but this required that the user separately configure a data source and manage it. In addition, features such as plugins and enums require support from both the EF and ADO.NET layers, forcing users to perform multiple setup actions at the different layers. With version 9, `UseNpgsql()` becomes a single point for configuration, for both the EF and ADO.NET levels. EF can now internally set up an NpgsqlDataSource, automatically applying all the necessary configuration to it, and also exposes an API to allow users to apply arbitrary configuration to it as well: @@ -31,7 +31,7 @@ In the above code, the following configuration gestures are performed: 3. `MapEnum()` maps a .NET enum type. Like `UseNodaTime()`, this also used to require a separate ADO.NET configuration gesture, but is now done automatically. As an added bonus, doing this now also adds the enum to the model, causing the enum to be created in the database via EF's migrations. 4. `ConfigureDataSource()` exposes an NpgsqlDataSourceBuilder, which you can use to configure arbitrary ADO.NET options. In this example, the certificate is defined for the TLS authentication process. -For more information, see the [getting started docs](../index.html). +For more information, see the [getting started docs](../index.md). ### Improved configuration for enums and plugins diff --git a/conceptual/Npgsql/release-notes/4.0.md b/conceptual/Npgsql/release-notes/4.0.md index cea906c5..150b71b5 100644 --- a/conceptual/Npgsql/release-notes/4.0.md +++ b/conceptual/Npgsql/release-notes/4.0.md @@ -36,7 +36,7 @@ You can now use the new [Npgsql.NodaTime](../types/nodatime.md) to have Npgsql m ## Json.NET -Another plugin, [Npgsql.Json.NET](../types/jsonnet.md), works with [Newtonsoft Json.NET](https://www.newtonsoft.com/json) to automatically serialize and deserialize PostgreSQL's `jsonb` and `json` types to your objects, providing a seamless database JSON programming experience. Instead of working with strings which you have to serialize and deserialize, Npgsql does it for you. +Another plugin, [Npgsql.Json.NET](../types/json.md), works with [Newtonsoft Json.NET](https://www.newtonsoft.com/json) to automatically serialize and deserialize PostgreSQL's `jsonb` and `json` types to your objects, providing a seamless database JSON programming experience. Instead of working with strings which you have to serialize and deserialize, Npgsql does it for you. ## Other improvements diff --git a/conceptual/Npgsql/release-notes/8.0.md b/conceptual/Npgsql/release-notes/8.0.md index a63921aa..2e5b2429 100644 --- a/conceptual/Npgsql/release-notes/8.0.md +++ b/conceptual/Npgsql/release-notes/8.0.md @@ -53,12 +53,12 @@ For more information on registering Npgsql services in DI, see the documentation ## Other features * Allow using nullable value types with the generic `NpgsqlParameter`, e.g. `NpgsqlParameter`. -* Introduce a non-caching password provider callback via . -* Allow customizing System.Text.Json JsonSerializationOptions via . +* Introduce a non-caching password provider callback via . +* Allow customizing System.Text.Json JsonSerializationOptions via . * Improvements and cleanup for networking type mappings: * In addition to .NET , PostgreSQL `inet` can also mapped to be mapped to , which is an immutable struct containing both IP and netmask components. * PostgreSQL `cidr` is now mapped to the newly-introduced . The mapping to `ValueTuple` has been removed. -* Allow providing the root certificate programmatically via the new +* Allow providing the root certificate programmatically via the new Version 8.0 contains many other smaller features and bug fixes, [see the 8.0.0 milestone](https://github.com/npgsql/npgsql/milestone/97?closed=1) for the full list of issues. @@ -70,9 +70,9 @@ Npgsql 8.0 is fully compatible with NativeAOT and trimming (see above). While mo PostgreSQL type | Default .NET type ---------------------------------------- | -------------------------- -JSON POCO mapping, JsonNode and subtypes | -Unmapped enums, ranges, multiranges | -Read PostgreSQL records as .NET tuples | +JSON POCO mapping, JsonNode and subtypes | +Unmapped enums, ranges, multiranges | +Read PostgreSQL records as .NET tuples | Existing code using the above features will start throwing exceptions after upgrading to Npgsql 8.0; the exceptions provide explicit guidance on how to add the opt-ins. diff --git a/conceptual/Npgsql/security.md b/conceptual/Npgsql/security.md index 7277ecee..6d21c998 100644 --- a/conceptual/Npgsql/security.md +++ b/conceptual/Npgsql/security.md @@ -80,7 +80,7 @@ If the root CA of the server certificate isn't installed in your machine's CA st Note that Npgsql does not perform certificate revocation validation by default, since this is an optional extension not implemented by all providers and CAs. To turn on certificate revocation validation, specify `Check Certificate Revocation=true` on the connection string. -Finally, if the above options aren't sufficient for your scenario, you can call to provide your custom server certificate validation logic (this gets set on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)). +Finally, if the above options aren't sufficient for your scenario, you can call to provide your custom server certificate validation logic (this gets set on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)). ### Client certificates @@ -92,7 +92,7 @@ PostgreSQL may be configured to require valid certificates from connecting clien To provide a password for a client certificate, set either the `SSL Password` (6.0 and higher) or `Client Certificate Key` (5.0 and lower) connection string parameter. -Finally, you can call , or to programmatically provide a certificate, multiple certificates or a callback which returns certificates (this works like on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)). +Finally, you can call , or to programmatically provide a certificate, multiple certificates or a callback which returns certificates (this works like on the underlying .NET [`SslStream`](https://docs.microsoft.com/dotnet/api/system.net.security.sslstream.-ctor#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_)). > [!NOTE] > Npgsql supports .PFX and .PEM certificates starting with 6.0. Previously, only .PFX certificates were supported. diff --git a/conceptual/Npgsql/types/json.md b/conceptual/Npgsql/types/json.md index 5aa9888f..3903a391 100644 --- a/conceptual/Npgsql/types/json.md +++ b/conceptual/Npgsql/types/json.md @@ -46,7 +46,7 @@ With this mapping style, you're fully responsible for serializing/deserializing If your column JSON contains documents with a stable schema, you can map them to your own .NET types (or POCOs). The provider will use System.Text.Json APIs under the hood to serialize instances of your types to JSON documents before sending them to the database, and to deserialize documents coming back from the database. This effectively allows mapping an arbitrary .NET type - or object graph - to a single column in the database. -Starting with Npgsql 8.0, to use this feature, you must first enable it by calling on your , or, if you're not yet using data sources, on `NpgsqlConnection.GlobalTypeMapper`: +Starting with Npgsql 8.0, to use this feature, you must first enable it by calling on your , or, if you're not yet using data sources, on `NpgsqlConnection.GlobalTypeMapper`: ### [NpgsqlDataSource](#tab/datasource) diff --git a/docfx.json b/docfx.json index f954c97c..35cf8826 100644 --- a/docfx.json +++ b/docfx.json @@ -3,14 +3,14 @@ { "src": [ { - "files": [ "src/**/*.csproj" ], + "files": [ "src/Npgsql/Npgsql.csproj" ], "exclude": [ "src/MSI/**", "src/VSIX/**", "**/bin/**", "**/obj/**" ], - "cwd": "Npgsql/" + "src": "Npgsql/" } ], "dest": "obj/api/Npgsql", "properties": { - "TargetFramework": "netstandard2.1" + "TargetFramework": "net8.0" } }, { @@ -18,12 +18,12 @@ { "files": [ "src/**/*.csproj" ], "exclude": [ "**/bin/**", "**/obj/**", "Properties/NpgsqlStrings.*" ], - "cwd": "EFCore.PG" + "src": "EFCore.PG" } ], "dest": "obj/api/EFCore.PG", "properties": { - "TargetFramework": "net6.0" + "TargetFramework": "net8.0" } } ], @@ -35,27 +35,27 @@ "content": [ { "files": [ "**/*.yml" ], - "cwd": "obj/api/Npgsql", + "src": "obj/api/Npgsql", "dest": "doc/api" }, { "files": [ "**/*.yml" ], - "cwd": "obj/api/EFCore.PG", + "src": "obj/api/EFCore.PG", "dest": "efcore/api" }, { "files": [ "**.md", "toc.yml" ], - "cwd": "conceptual/Npgsql", + "src": "conceptual/Npgsql", "dest": "doc" }, { "files": [ "**.md", "toc.yml" ], - "cwd": "conceptual/EFCore.PG", + "src": "conceptual/EFCore.PG", "dest": "efcore" }, { "files": [ "**.md", "toc.yml" ], - "cwd": "conceptual/EF6.PG", + "src": "conceptual/EF6.PG", "dest": "ef6" }, {