Merge pull request #6219 from EnterpriseDB/connectors_nov_release

.NET connector: Release branch for 8.0.5.1

product_docs/docs/net_connector/8.0.5.1/01_release_notes.mdx

@@ -0,0 +1,17 @@
+---
+title: "Release notes"
+---
+
+Released: 21 Nov 2024
+
+The EDB .NET Connector provides connectivity between a .NET client application and an EDB Postgres Advanced Server database server.
+
+New features, enhancements, bug fixes, and other changes in the EDB .NET Connector `8.0.5.1` include:
+
+| Type           | Description                                                                                                                                                                                                                                        | Addresses |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
+| Upstream merge | Merged with community .NET driver version 8.0.5 and EF Core Driver 8.0.10. See [release notes](https://www.npgsql.org/doc/release-notes/8.0.html) for more information about merge updates.                                                        |           |
+| Bug fix        | Fixed a performance issue. Performance is now improved when reading data while targeting .NET Framework 4.7.2, 4.8, and 4.8.1.                                                                                                                     | #41979    |
+| Enhancement    | Added support for EDB Postgres Advanced Server 17.2.                                                                                                                                                                                               |           |
+| Enhancement    | Added support for `IS TABLE OF`. EDB Postgres Advanced Server supports Oracle nested table collection types created with `CREATE TYPE ... AS TABLE OF` statements. See [Using nested tables](./using_nested_table_types.mdx) for more information. |           |
+| Deprecation    | Removed .NET5, .NET6, and .NET7 targets as they have reached end of support.                                                                                                                                                                       |           |

product_docs/docs/net_connector/8.0.5.1/02_requirements_overview.mdx

@@ -0,0 +1,20 @@
+---
+title: "Product compatibility"
+---
+
+<div id="requirements_overview" class="registered_link"></div>
+
+These are the supported versions and platforms for the EDB .NET Connector.
+
+The EDB .NET Connector is certified with EDB Postgres Advanced Server version 11 and later.
+
+The EDB .NET Connector graphical installers are supported on the following Windows platforms:
+
+64-bit Windows:
+
+-   Windows Server 2019 and 2022
+-   Windows 10 and 11
+
+32-bit Windows:
+
+-   Windows 10

product_docs/docs/net_connector/8.0.5.1/03_the_advanced_server_net_connector_overview.mdx

@@ -0,0 +1,39 @@
+---
+title: "EDB .NET Connector overview"
+
+---
+
+<div id="the_advanced_server_net_connector_overview" class="registered_link"></div>
+
+EDB .NET Connector is a .NET data provider that allows a client application to connect to a database stored on an EDB Postgres Advanced Server host. The .NET Connector accesses the data directly, allowing the client application optimal performance, a broad spectrum of functionality, and access to EDB Postgres Advanced Server features.
+
+The .NET Connector supports the following frameworks:
+
+-   .NET 8.0
+-   .NET Framework 4.7.2, 4.8, and 4.8.1
+-   .NET Standard 2.0 and 2.1
+
+
+## The .NET class hierarchy
+
+The .NET class hierarchy contains classes that you can use to create objects that control a connection to the EDB Postgres Advanced Server database and manipulate the data stored on the server. The following are a few of the most commonly used object classes.
+
+`EDBDataSource`
+
+ `EDBDataSource` is the entry point for all the connections made to the database. It's responsible for issuing connections to the server and efficiently managing them. Starting with EDB .NET Connector 7.0.4.1, you no longer need direct instantiation of `EDBConnection`. Instantiate `EDBDataSource` and use the method provided to create commands or execute queries.
+
+`EDBConnection`
+
+ The `EDBConnection` class represents a connection to EDB Postgres Advanced Server. An `EDBConnection` object contains a `ConnectionString` that tells the .NET client how to connect to an EDB Postgres Advanced Server database. Obtain `EDBConnection` from an `EDBDataSource` instance, and use it directly only in specific scenarios, such as transactions.
+
+`EDBCommand`
+
+ An `EDBCommand` object contains a SQL command that the client executes against EDB Postgres Advanced Server. Before you can execute an `EDBCommand` object, you must link it to an `EDBConnection` object.
+
+`EDBDataReader`
+
+ An `EDBDataReader` object provides a way to read an EDB Postgres Advanced Server result set. You can use an `EDBDataReader` object to step through one row at a time, forward only.
+
+`EDBDataAdapter`
+
+ An `EDBDataAdapter` object links a result set to the EDB Postgres Advanced Server database. You can modify values and use the `EDBDataAdapter` class to update the data stored in an EDB Postgres Advanced Server database.

product_docs/docs/net_connector/8.0.5.1/04_installing_and_configuring_the_net_connector.mdx

@@ -0,0 +1,290 @@
+---
+title: "Installing and configuring the .NET Connector"
+
+---
+
+<div id="installing_and_configuring_the_net_connector" class="registered_link"></div>
+
+## Installing the .NET Connector
+
+You can install the EDB .NET Connector using either the EDB installer or the installer from NuGet.org.
+
+### Installing and configuring the .NET Connector from NuGet.org
+
+#### Install NuGet package via command line
+
+Launch a terminal from your solution folder and run: 
+
+```text
+dotnet add package EnterpriseDB.EDBClient
+```
+
+This command downloads and installs the EDB .NET Connector matching your .NET version. Your project is then ready to import the EDB .NET Connector namespace: 
+
+```text
+using EnterpriseDB.EDBClient;
+```
+
+You can find all the EDB .NET Connector satellite packages at [NuGet.org](https://www.nuget.org/profiles/EnterpriseDB).
+
+For more information, see the [EDB .NET Connector Now Published on NuGet](https://www.enterprisedb.com/blog/improving-developer-experience-updated-edb-net-connector-now-published-nuget) blog post.
+
+#### Install NuGet package via Visual Studio interface
+
+1. Right-click your project or solution and select **Manage NuGet package**.
+1. Search the package using `enterprisedb.edbclient` as the search text.
+1. Select the EnterpriseDB.EDBClient package.
+1. Select **Install** to proceed to package download and installation.
+
+This command downloads and installs the EDB .NET Connector matching your .NET version. Your project is then ready to import the EDB .NET Connector namespace: 
+
+```text
+using EnterpriseDB.EDBClient;
+```
+
+For more information, see the [EDB .NET Connector Now Published on NuGet](https://www.enterprisedb.com/blog/improving-developer-experience-updated-edb-net-connector-now-published-nuget) blog post.
+
+### Installing the .NET Connector using EDB installer
+
+You can use the EDB .NET Connector installer to add the .NET Connector to your system. The installer is available from [the EDB website](https://www.enterprisedb.com/software-downloads-postgres). 
+
+1. After downloading the installer, right-click the installer icon, and select **Run As Administrator**. When prompted, select an installation language and select **OK** to continue to the Setup window.
+
+  ![The .NET Connector Installation wizard](images/dotnet_installation_wizard.png)
+
+1. Select **Next**.
+
+  ![The Installation dialog box](images/dotnet_installation_dialog.png)
+
+1.  Use the Installation Directory dialog box to specify the directory in which to install the connector. Select **Next**.
+
+  ![The Ready to Install dialog box](images/ready_to_install.png)
+
+1. To start the installation, on the Ready to Install dialog box, select **Next**. Popups confirm the progress of the installation wizard.
+
+  ![The installation is complete](images/dotnet_installation_complete.png)
+
+1. When the wizard informs you that it has completed the setup, select **Finish**.
+
+You can also use StackBuilder Plus to add or update the connector on an existing EDB Postgres Advanced Server installation. 
+
+1. To open StackBuilder Plus, from the Windows **Apps** menu, select **StackBuilder Plus**.
+
+  ![Starting StackBuilder Plus](images/starting_stackbuilder_plus.png)
+
+1. When StackBuilder Plus opens, follow the onscreen instructions.
+
+1. From the Database Drivers node of the tree control, select the **EnterpriseDB.Net Connector** option.
+
+  ![Selecting the Connectors installer](images/selecting_the_connectors_installer.png)
+
+1. Follow the directions of the onscreen wizard to add or update an installation of an EDB Connector.
+
+### Configuring the .NET Connector
+
+For information about configuring the .NET Connector in each environment, see:
+
+-   **Referencing the Library Files.** [General configuration information](#referencing_the_library_files) applicable to all components.
+-   **.NET 8.0** Instructions for configuring for use with [.NET 8.0](#setup_8_0).
+-   **.NET Framework 4.7.2** Instructions for configuring for use with [.NET framework 4.7.2](#net-framework-472).
+-   **.NET Framework 4.8** Instructions for configuring for use with [.NET Framework 4.8](#net-framework-48).
+-   **.NET Framework 4.8.1** Instructions for configuring for use with [.NET Framework 4.8.1](#net-framework-481).
+-   **.NET Standard 2.0** Instructions for configuring for use with [.NET Standard 2.0](#standard_setup_2_0).
+-   **.NET Standard 2.1** Instructions for configuring for use with [.NET Standard 2.1](#standard_setup_2_1).
+-   **.NET EntityFramework Core** Instructions for configuring for use with [.NET EntityFramework Core](#entity_setup).
+
+#### Referencing the library files
+
+<div id="referencing_the_library_files" class="registered_link"></div>
+
+To reference library files with Microsoft Visual Studio:
+
+1.  In the Solution Explorer, select the project.
+2.  Select **Project > Add Reference**.
+3.  In the Add Reference dialog box, browse to select the appropriate library files.
+
+Optionally, you can copy the library files to the specified location.
+
+Before you can use an EDB .NET class, you must import the namespace into your program. Importing a namespace makes the compiler aware of the classes available in the namespace. The namespace is `EnterpriseDB.EDBClient`.
+
+The method you use to include the namespace varies by the type of application you're writing. For example, the following command imports a namespace into an `ASP.NET` page:
+
+```text
+ <% import namespace="EnterpriseDB.EDBClient" %>
+```
+
+To import a namespace into a C# application, use:
+
+```text
+ using EnterpriseDB.EDBClient;
+```
+
+#### .NET framework setup
+
+Each .NET version has specific setup instructions.
+
+<div id="setup_8_0" class="registered_link"></div>
+
+##### .NET 8.0
+
+For .NET 8.0, the data provider installation path is:
+
+`C:\Program Files\edb\dotnet\net8.0\`
+
+You must add the following dependencies to your project:
+
+`EnterpriseDB.EDBClient.dll`
+
+Depending upon the type of application you use, you may be required to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and other information about referencing library files.
+
+##### .NET Framework 4.7.2
+
+For .NET Framework 4.7.2, the data provider installation path is:
+
+ `C:\Program Files\edb\dotnet\net472\`.
+
+You must add the following dependency to your project. You may also need to add other dependencies from the same directory:
+
+- `EnterpriseDB.EDBClient.dll`
+
+Depending on your application type, you might need to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and the other information about referencing the library files.
+
+##### .NET Framework 4.8
+
+For .NET Framework 4.8, the data provider installation path is:
+
+ `C:\Program Files\edb\dotnet\net48\`.
+
+You must add the following dependency to your project. You may also need to add other dependencies from the same directory:
+
+- `EnterpriseDB.EDBClient.dll`
+
+Depending on your application type, you might need to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and the other information about referencing the library files.
+
+##### .NET Framework 4.8.1
+
+For .NET Framework 4.8.1, the data provider installation path is:
+
+ `C:\Program Files\edb\dotnet\net481\`.
+
+You must add the following dependency to your project. You may also need to add other dependencies from the same directory:
+
+- `EnterpriseDB.EDBClient.dll`
+
+Depending on your application type, you might need to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and the other information about referencing the library files.
+
+<div id="standard_setup_2_0" class="registered_link"></div>
+
+##### .NET Standard 2.0
+
+For .NET Standard Framework 2.0, the data provider installation path is:
+
+ `C:\Program Files\edb\dotnet\netstandard2.0\`.
+
+You must add the following dependencies to your project:
+
+- `EnterpriseDB.EDBClient.dll`
+
+- `System.Threading.Tasks.Extensions.dll`
+
+- `System.Runtime.CompilerServices.Unsafe.dll`
+
+- `System.ValueTuple.dll`
+
+Depending on your application type, you might need to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and the other information about referencing the library files.
+
+<div id="standard_setup_2_1" class="registered_link"></div>
+
+##### .NET Standard 2.1
+
+For .NET Standard Framework 2.1, the data provider installation path is `C:\Program Files\edb\dotnet\netstandard2.1\`.
+
+The following shared library files are required:
+
+- `EnterpriseDB.EDBClient.dll`
+
+- `System.Memory.dll`
+
+- `System.Runtime.CompilerServices.Unsafe.dll`
+
+- `System.Text.Json.dll`
+
+- `System.Threading.Tasks.Extensions.dll`
+
+- `System.ValueTuple.dll`
+
+Depending on your application type, you might need to import the namespace into the source code. See [Referencing the library files](#referencing_the_library_files) for this and the other information about referencing the library files.
+
+<div id="entity_setup" class="registered_link"></div>
+
+##### .NET Entity Framework Core
+
+To configure the .NET Connector for use with Entity Framework Core, the data provider installation path is:
+
+`C:\Program Files\edb\dotnet\EF.Core\EFCore.PG\net8.0`
+The following shared library file is required:
+
+- `EnterpriseDB.EDBClient.EntityFrameworkCore.PostgreSQL.dll`
+
+See [Referencing the library files](#referencing_the_library_files) for information about referencing the library files.
+
+The following NuGet packages are required:
+
+-  `Microsoft.EntityFrameworkCore.Design`
+
+-  `Microsoft.EntityFrameworkCore.Relational`
+
+-  `Microsoft.EntityFrameworkCore.Abstractions`
+
+
+For usage information about Entity Framework Core, see the [Microsoft documentation](https://learn.microsoft.com/en-us/ef/core/).
+
+**Prerequisite**
+
+To open a command prompt:
+
+Select **Tools > Command Line > Developer Command Prompt**.
+
+Install dotnet-ef (using the command prompt),
+
+  `dotnet tool install --global dotnet-ef`
+
+**Sample project**
+
+Create a new Console Application based on .NET 8.0.
+
+Add Reference to the following EDB assemblies:
+
+-  `EnterpriseDB.EDBClient.EntityFrameworkCore.PostgreSQL.dll`
+
+-  `EnterpriseDB.EDBClient.dll`
+
+Add the following NuGet packages:
+
+-  `Microsoft.EntityFrameworkCore.Design`
+
+-  `Microsoft.EntityFrameworkCore.Relational`
+
+-  `Microsoft.EntityFrameworkCore.Abstractions`
+
+**Database-first scenario**
+
+Issue the following command to create model classes corresponding to all objects in the specified database:
+
+```text
+dotnet ef dbcontext scaffold Host=<HOST>;Database=<DATABASE>;Username=<USER>;Password=<PASSWORD>;Port=<PORT> EnterpriseDB.EDBClient.EntityFrameworkCore.PostgreSQL -o Models
+```
+
+**Code-first scenario**
+
+Add code for defining a DbContext and create, read, update, and delete operations. 
+
+For more details, see the Microsoft documentation.
+
+Issue the following commands to create the initial database and tables:
+
+```text
+  dotnet ef migrations add InitialCreate --context BloggingContext
+
+  dotnet ef database update --context BloggingContext
+```

product_docs/docs/net_connector/8.0.5.1/05_using_the_net_connector.mdx

@@ -0,0 +1,24 @@
+---
+title: "Using the .NET Connector"
+
+---
+
+<div id="using_the_net_connector" class="registered_link"></div>
+
+These examples show how you can use the EDB object classes that are provided by the EDB .NET Connector. These object classes allow a .NET application to connect to and interact with an EDB Postgres Advanced Server database.
+
+To use these examples, place the .NET library files in the same directory as the compiled form of your application. All of these examples are written in C#, and each is embedded in an ASP.NET page. The same logic and code applies to other .NET applications (WinForm or console applications, for example).
+
+Create and save the following `web.config` file in the same directory as the sample code. The examples make use of the `DB_CONN_STRING` key from this configuration file to return a connection string from the EDB Postgres Advanced Server host.
+
+```text
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+<appSettings>
+      <add key="DB_CONN_STRING" value="Server=127.0.0.1;Port=5444;
+      User Id=enterprisedb;Password=enterprisedb;Database=edb" />
+</appSettings>
+</configuration>
+```
+
+An EDB Postgres Advanced Server connection string for an ASP.NET web application is stored in the `web.config` file. If you're writing an application that doesn't use ASP.NET, provide the connection information in an application configuration file, such as `app.config`.