diff --git a/.gitignore b/.gitignore index 1f08fe8..9e57944 100644 --- a/.gitignore +++ b/.gitignore @@ -25,7 +25,7 @@ reflog.md # Ignore personal configuration files *.ps1rc -.vscode/ +!.vscode/ # Ignore IDE-specific files .vs/ @@ -55,8 +55,8 @@ Modules/ *.old # SQL Server files -*.mdf -*.ldf +# *.mdf # Allowed for including tests sample database +# *.ldf # Allowed for including tests sample database *.ndf # VS Code files for those working on multiple tools diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..cd4f5d4 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "cheatsheet" + ] +} \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..7e11181 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,79 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [BrooksV](https://github.com/BrooksV). All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). + +[homepage]: https://www.contributor-covenant.org diff --git a/README.md b/README.md index b13d628..fc4fff7 100644 --- a/README.md +++ b/README.md @@ -1,355 +1,200 @@ -
-

SqlQueryClass

-

Module that create an instance of a PowerShell class which is used to execute SQL Queries and manages output as DataTable, DataAdapter, DataSet, DataRows, or NonQuery result object.

- -
- - -
-

- # SqlQueryClass -Provides functionality for executing SQL queries and managing SQL datasets - -## Description - -The SqlQueryClass module provides a set of functions and cmdlets for working with SQL Server databases. It includes functionality for connecting to a SQL Server, executing SQL queries, and managing the results in datasets. - -[![SqlQueryClass@PowerShell Gallery][BadgeIOCount]][PSGalleryLink] -![WorkFlow Status][WorkFlowStatus] - -## Module Install - -SqlQueryClass is in early development phase. Please read through [ChangeLog](/CHANGELOG.md) for all updates. - -Stable releases can be installed from the PowerShell Gallery: - -```PowerShell -Install-Module -Name SqlQueryClass -Verbose -``` - -To load a local build of the module, use `Import-Module` as follows: - -```PowerShell -Import-Module -Name ".\dist\SqlQueryClass\SqlQueryClass.psd1" -Force -verbose -``` - -## Requirements - -- Tested with PowerShell 5.1 and 7.5x -- No known dependencies for usage -- VS Code and clone [Brooks Vaughn's SqlQueryClass](https://github.com/BrooksV/SqlQueryClass) Repository -- Module build process uses [Manjunath Beli's](https://github.com/belibug) [ModuleTools](https://github.com/belibug) module. - -## ToDo - -- [ ] Seek peer review and comments -- [ ] Integrate feedback -- [ ] Improve Documentation - -## LONG DESCRIPTION +The SqlQueryClass module provides a set of functions and cmdlets for working with SQL databases. It includes functionality for connecting, executing SQL queries, and managing output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result objects. -This module is designed to simplify database operations and improve productivity by offering a set of easy-to-use cmdlets. +## `SqlQueryClass` Module and Status Details -Classes [SqlQueryDataSet] and [SqlQueryTable] are defined in the `.\src\private\SqlQueryClass.ps1` file. +Name | Version | PS Compatibility | Project Uri (GitHub) +------------- | ------- | ---------------- | ------------------------------------------------------------------------------------ +SqlQueryClass | 0.1.1 | 5.1 | [https://github.com/BrooksV/SqlQueryClass](https://github.com/BrooksV/SqlQueryClass) -New-SqlQueryDataSet helper function is used to creates an instance of the [SqlQueryDataSet] class. This is necessary as classes within modules are local to the module and are not directly accessible outside of the module. - -It is best to read the details in the details `.\src\private\SqlQueryClass.ps1` and in `.\src\public\New-SqlQueryDataSet.ps1` files. +[PSGalleryLink]: https://www.powershellgallery.com/packages/SqlQueryClass/ +[BadgeIOCount]: https://img.shields.io/powershellgallery/dt/SqlQueryClass.svg?label=downoads%20SqlQueryClass%40PSGallery +[WorkFlowStatus]: https://img.shields.io/github/actions/workflow/status/BrooksV/SqlQueryClass/tests.yml?label=tests.yml%20build -## How Build `SqlQueryClass` Module +[![maintainer](https://img.shields.io/badge/maintainer-BrooksV-orange)](https://github.com/BrooksV) +[![License](https://img.shields.io/github/license/BrooksV/SqlQueryClass)](https://github.com/BrooksV/SqlQueryClass/blob/main/LICENSE) +[![contributors](https://img.shields.io/github/contributors/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/graphs/contributors/) +[![last-commit](https://img.shields.io/github/last-commit/BroksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/commits/) +[![issues](https://img.shields.io/github/issues/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/issues/) +[![issues-closed](https://img.shields.io/github/issues-closed/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/issues?q=is%3Aissue+is%3Aclosed) +[![GitHub stars](https://img.shields.io/github/stars/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/stargazers) +[![GitHub forks](https://img.shields.io/github/forks/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/network/members) +[![GitHub pull requests](https://img.shields.io/github/issues-pr/BrooksV/SqlQueryClass.svg)](https://github.com/BrooksV/SqlQueryClass/pulls) -### Setup +### Build and Release Statistics -- Uses SQL Express but should work with other SQL Databases with proper connection strings and credentials -- Requires VS Code -- For Contributors, Fork the [SqlQueryClass](https://github.com/BrooksV/SqlQueryClass) repository -- Clone the repository or fork to local pc. I like using c:\git as my local repository folder. Subfolder `SqlQueryClass` will be created with the GiHib repository contents -- Install [Manjunath Beli's ModuleTools](https://github.com/belibug/ModuleTools) module as the module build process uses ModuleTools -- - Find-Module -Name ModuleTools | Install-Module -Scope CurrentUser -Verbose -- Note that a sample SQL Express database file (.\tests\TestDatabase1.mdf) is included for pester tests. The database configuration is set in .\tests\TestDatabase1.parameters.psd1 +[![SqlQueryClass@PowerShell Gallery][BadgeIOCount]][PSGalleryLink] +![WorkFlow Status][WorkFlowStatus] +![Build Status](https://img.shields.io/github/actions/workflow/status/BrooksV/SqlQueryClass/ci.yml?label=ci.yml%20build) -#### Source Files used in the Module +![Version](https://img.shields.io/github/v/release/BrooksV/SqlQueryClass.svg?label=version) +![GitHub All Releases](https://img.shields.io/github/downloads/BrooksV/SqlQueryClass/total.svg?label=release%20dl%20all%40GitHub) +![GitHub release (latest by date)](https://img.shields.io/github/downloads/BrooksV/SqlQueryClass/latest/total.svg?label=release%20dl%20by%20date%40GitHub) +![Downloads](https://img.shields.io/github/downloads/BrooksV/SqlQueryClass/total.svg?label=total%20release%20dl%40GitHub) -- Public functions that are exported, are separate files in the .\src\public folder. -- Private functions that are local to the Module, are separate files in the .\src\private folder. -- - Class Definitions and Enums are not accessible outside of the Module and cannot be accessed directly like Public Functions are. This is a PowerShell limitation. -- - - Classes [SqlQueryDataSet] and [SqlQueryDataSetParms] and enum ResultType used in the Module are defined in file .\src\private\SqlQueryClass.ps1 file. The classes have properties and methods used to maintain a Database connections and result sets making it useful WPF Data binding. -- Resources are files and folders in the .\src\resources folder that needs to be included with the Manifest and Module +### Related Links -#### `SqlQueryClass` Module Build Process +- [LicenseUri](https://github.com/BrooksV/SqlQueryClass/blob/main/LICENSE) +- [ProjectUri](https://github.com/BrooksV/SqlQueryClass) -- Create a local branch for your changes -- - Use descriptive name that reflects the type of changes for branch for example features/database-table-access -- Update the build version using Update-MTModuleVersion (Find-Module -Name ModuleTools) -- Commit your changes to the branch -- Run the Pester Teats using Invoke-MTTest (Find-Module -Name ModuleTools) -- Build the Module output using Invoke-MTBuild -Verbose (Find-Module -Name ModuleTools) -- - Outputs to the .\dist\SqlQueryClass folder -- - Combines the file contents of the files in Public and Private folder into .\dist\SqlQueryClass\SqlQueryClass.psd1 and exports the Public Functions -- - Generates the .\dist\SqlQueryClass\SqlQueryClass.psd1 Manifest file from the settings in .\project.json -- - Resources (.\src\resources) folder content is copied to .\dist\SqlQueryClass folder -- Run the Pester Teats using Invoke-MTTest (Find-Module -Name ModuleTools) -- Make corrections, repeat the build process -- For Contributors -- - Create an Issue if one does not exist that addresses the proposed changes -- - Upstream your branch -- - Create a Pull request +### Module Tags / Keywords -#### Publishing `SqlQueryClass` Module to GitHub +[PowerShell], [Database], [SQL], [SQLServer], [SQLQuery], [DataAdapter], [DataSet], [DataTable] -Stage and Commit Your Changes +## Installation ```powershell -git add . -git commit -m "Implemented database and table access functions" +Install-Module -Name SqlQueryClass -Repository PSGallery -Scope CurrentUser ``` -Update remote repository with branch changes +To load a local build of the module, use Import-Module as follows: ```powershell -# List status of remote repository -git branch -r -# Create Branch on remote repository if needed -# git push --set-upstream origin features/database-table-access -# Push branch changes to remote branch in repository -git push origin features/database-table-access +Import-Module -Name "C:\Git\SqlQueryClass\dist\SqlQueryClass\SqlQueryClass.psd1" -Force -verbose ``` -Create a Pull Request on remote repository - -- Go to [SqlQueryClass GitHub repository](https://github.com/BrooksV/SqlQueryClass) -- Click on "Compare & pull request" for your branch -- Provide a meaningful title and description for the PR -- Select the base branch (main) to merge into -- Click "Create pull request" - -Code Review and Feedback +### Requirements -- Engage with Repository Owner or collaborators to review the PR -- Address any feedback or requested changes by making additional commits to your branch and pushing them to the remote branch -- Ensure the PR passes any automated tests or checks - -Merge the Pull Request - -- Once the PR is approved and all checks pass, you can merge it into the main branch -- You can either use the "Merge pull request" button on GitHub or merge it locally and push the changes +- Tested with PowerShell 5.1 and 7.5x +- No known dependencies for usage +- VS Code and clone [Brooks Vaughn's SqlQueryClass](https://github.com/BrooksV/SqlQueryClass) Repository +- Module build process uses [Manjunath Beli's](https://github.com/belibug) [ModuleTools](https://github.com/belibug) module. +- Test scripts requires the Pester module and SQL Express +- Includes sample SQL Express database file used in test scripts -Cleanup +### Features -- After merging, you can delete the feature branch from the remote repository to keep it clean +- Includes helper functions (not used by the Classes as they have there own methods for database access and management) +- - Class Constructor +- - SQL Query and NonQuery execute functions +- - Attach and Detach Database functions +- - List Database and Table functions +- - Create SQL Connection function +- Uses PowerShell Classes to: +- - Manage database connections and configuration persistence +- - Execute SQL queries +- - Manage multiple SQL Query configurations and execution results as persist data +- - Supports multiple query types, output data types +- - Includes database schema, table, and DDL methods +- - Support for multiple SQL servers using multiple instances of the parent class -```powershell -git push origin --delete features/database-table-access -``` +## Usage -- Optionally, delete the local branch +The SqlQueryClass Module was developed to support data binding of WPF (Windows Presentation Framework) elements to DataTables and uses SQL Adapter features for CRUD operations. Having a single class object is very convenient since it allows for maintaining connectivity, queries, and results. -```powershell -git branch -d features/database-table-access -``` -These steps will ensure your changes are integrated into the main branch and your repository remains organized. +It can be useful in any PS script that needs to read and write to SQL databases. For quick and simple, the Module's helper functions are also a consideration. When needing to use the Classes, use the `New-SqlQueryDataSet` function which calls the Parent Class [SqlQueryDataSet]::New() constructor and return an instance of the class. -#### Publishing `SqlQueryClass` Module to PowerShell Gallery +### New-SqlQueryDataSet Helper Function Used to Create Parent [SqlQueryDataSet] Class Instance ```powershell -$data = Get-MTProjectInfo -$ApiKey = "your-api-key-here" -Publish-Module -Path $data.OutputModuleDir -NuGetApiKey $ApiKey -Repository PSGallery +$result = New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] ``` -### New-SqlQueryDataSet Helper Function to Create Class Instance +These and other properties can be configured after the instance is created and before the desired execution method is called. -The main cmdlet provided by this module is New-SqlQueryDataSet, which returns an object instance of [SqlQueryDataSet] class. Note that all the parameters are optional. +#### New-SqlQueryDataSet Help Links -```powershell -$testQuery = New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] -``` +- For usage examples, the [New-SqlQueryDataSets.tests.ps1](.\tests\New-SqlQueryDataSets.tests.ps1) contains a full suite of usage examples used in the Pester tests. +- For examples, type: "Get-Help New-SqlQueryDataSet -Examples" +- For detailed information, type: "Get-Help New-SqlQueryDataSet -Detailed" +- For technical information, type: "Get-Help New-SqlQueryDataSet -Full" +- See [API Guide and Class Documentation](api.guide.md) for detailed information about the module functions and classes. -#### Other Helper Functions in the SqlQueryClass Module +### Example 1: Create Class and Initializes with Database and Query Settings ```powershell -Get-Command -Module SqlQueryClass -Syntax - -Dismount-Database [[-connectionString] ] [[-Database] ] [-Quiet] -Get-Database [[-connectionString] ] [[-query] ] [-Quiet] -Get-DatabaseTable [[-connectionString] ] [[-query] ] [-Quiet] -Invoke-DatabaseNonQuery [[-connectionString] ] [[-NonQuery] ] [-Quiet] -Invoke-DatabaseQuery [[-connectionString] ] [[-query] ] [-Quiet] -Mount-Database [[-connectionString] ] [[-Database] ] [[-DatabaseFilePath] ] [-Quiet] -New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] +$result = New-SqlQueryDataSet -SQLServer "myServer" -Database "myDB" -Query "SELECT * FROM myTable" ``` -## Summary of Classes - -An instance of Class [SqlQueryDataSet] is used to maintain the DataBase configuration and connection details. - -All the properties and methods defined in the [SqlQueryDataSet] class are referenced through the object returned by calling helper function New-SqlQueryDataSet. +### Example 2: Create Class and Initializes with Connection String and Query Settings ```powershell -class SqlQueryDataSet { - [string]$SQLServer - [string]$Database - [int]$ConnectionTimeout = 5 - [int]$CommandTimeout = 600 - [string]$ConnectionString - [object]$SQLConnection - [int]$TableIndex = 0 - [System.Collections.Generic.List[SqlQueryTable]]$Tables - [System.Collections.Hashtable]$TableNames = @{} - [bool]$DisplayResults = $True - [bool]$KeepAlive = $False -... +$result = New-SqlQueryDataSet -ConnectionString "Server=myServer;Database=myDB;User Id=myUser;Password=myPass;" -Query "SELECT * FROM myTable" -DisplayResults $false ``` - -There are many methods and ways to add a SQL Query. When a query is prepared, an instance of [SqlQueryTable] is created and added to the [System.Collections.Generic.List[SqlQueryTable]]$Tables property of the returned object. -An instance of [SqlQueryTable] maintains the query configuration and the results of it's execution. Each unique query will have it's own instance of [SqlQueryTable]. +## How to Contribute -If a Query is added without a TableName being set, [SqlQueryDataSet]::GetTableFromQuery([String]$Query) will attempt to extract the TableName from the Query. This works best with simple Select From statements so it's always best to use a unique identifier as the TableName. It is not part of the SQL Query or it's executions. It is only used to locate the desired query and can be called anything that helps to uniquely identify the row in the Tables property. +1. Fork the repository. +2. Create a local branch for your changes. +3. Make your changes and commit them. +4. Push your changes to your fork. +5. Create a pull request. -To help in locating the desired Query and Result, [HashTable]$TableNames property TableName Key returns the Index value. There is also the [int]$TableIndex property that defaults Tables[TableIndex] when executing a query. +For detailed information on "How to Contribute", set up the development environment, and more, please refer to the [Developer and Contributor Guide](contributor.guide.md). -Class method [SqlQueryDataSet]::GetTableFromTableName([String]$TableName) will return Result as [SqlQueryTable] +This includes details on: -```powershell -class SqlQueryTable { - [int]$TableIndex = 0 - [string]$TableName = [string]::Empty - [string]$Query = [string]::Empty - [object]$SQLCommand = $null - [object]$SqlDataAdapter = $null - [ResultType]$ResultType = [ResultType]::NonQuery - [object]$Result = $null - [bool]$isDirty = $false - [string]$QueryFile = [string]::Empty - [SqlQueryDataSet]$Parent = $null - - # Constructor -empty object - SqlQueryTable () - { - Return - } -} -``` +- [Setup](contributor.guide.md#setup) +- [Source Files used in the Module](contributor.guide.md#source-files-used-in-the-module) +- [Module Build Process](contributor.guide.md#module-build-process) +- [Publishing `SqlQueryClass` Module to GitHub](contributor.guide.md#publishing-sqlqueryclass-module-to-github) +- [Code Review and Feedback](contributor.guide.md#code-review-and-feedback) +- [Merge the Pull Request](contributor.guide.md#merge-the-pull-request) +- [Cleanup](contributor.guide.md#cleanup) +- [Publishing `SqlQueryClass` Module to PowerShell Gallery](contributor.guide.md#publishing-sqlqueryclass-module-to-powershell-gallery) -The ResultsType property defines how the query will be executed and the DataType for the result. ResultType values are: DataTable; DataAdapter; DataSet; DataRows; and NonQuery. +### ToDo -ResultType of DataTable and DataRows use the [System.Data.SqlClient.SqlDataReader] approach to load() a DataTable object and return [SqlQueryTable]$table.Result as [System.Data.DataTable] or [Array][System.Data.DataRow] - -ResultType of DataAdapter and DataSet returns [SqlQueryTable]$table.Result as [System.Data.DataSet] and retains the SqlDataAdapter used in [SqlQueryTable]$table.SqlDataAdapter - -### [SqlQueryDataSet] and [SqlQueryDataSetParms] Class Methods and Properties +- [ ] Include database query checks to Pester Tests +- [ ] Add comment-based help sections to all CmdLets and Functions +- [ ] Seek peer review and comments +- [ ] Integrate feedback +- [ ] Improve Documentation +- [ ] Develop a Build-Readme.ps1 script to support README.md updates to code changes -There are more then 27+ methods and are best listed by running the following with Database connection and Query settings: +## Module Exported Functions ```powershell -$testQuery = New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] -$testquery | GM -$testquery.Tables | GM +Get-Command -Module "SqlQueryClass" -Syntax + +- Dismount-Database [[-connectionString] ] [[-Database] ] [-Quiet] +- Get-Database [[-connectionString] ] [[-query] ] [-Quiet] +- Get-DatabaseTable [[-connectionString] ] [[-query] ] [-Quiet] +- Invoke-DatabaseNonQuery [[-connectionString] ] [[-NonQuery] ] [-Quiet] +- Invoke-DatabaseQuery [[-connectionString] ] [[-query] ] [-Quiet] +- Mount-Database [[-connectionString] ] [[-Database] ] [[-DatabaseFilePath] ] [-Quiet] +- New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] ``` -### New-SqlQueryDataSet Examples +### API Guide Overview -See .\tests\New-SqlQueryDataSets.tests.ps1 file for a fully set of usage examples used in the Pester Tests +For detailed API documentation, please refer to the [API Guide](api.guide.md). -Parameters are all optional but most of the properties will still need to be configured through the Class instance before an execute query is called. +This includes details on: -The most common usage examples are: +- [Functions](api.guide.md#functions) + - [Dismount-Database](api.guide.md#dismount-database) + - [Get-Database](api.guide.md#get-database) + - [Get-DatabaseTable](api.guide.md#get-database-table) + - [Invoke-DatabaseNonQuery](api.guide.md#invoke-database-non-query) + - [Invoke-DatabaseQuery](api.guide.md#invoke-database-query) + - [Mount-Database](api.guide.md#mount-database) + - [New-SqlQueryDataSet](api.guide.md#new-sql-query-data-set) +- [Classes](api.guide.md#classes) + - [SqlQueryDataSet Parent Class Details](api.guide.md#sql-query-data-set-parent-class-details) + - [Class SqlQueryDataSet Properties](api.guide.md#class-sql-query-data-set-properties) + - [Class SqlQueryDataSet Methods](api.guide.md#class-sql-query-data-set-methods) + - [Child Class SqlQueryTable Properties](api.guide.md#child-class-sql-query-table-properties) + - [Child Class SqlQueryTable Methods](api.guide.md#child-class-sql-query-table-methods) -```powershell -# Using a connection string, defining a query, and setting TableName -$result = New-SqlQueryDataSet -ConnectionString "Server=myServer;Database=myDB;User Id=myUser;Password=myPass;" -Query "SELECT * FROM INFORMATION_SCHEMA.COLUMNS" -TableName TableSchema +### Class Overview -# Create an instance of the [SqlQueryDataSet] class with Database configuration and defining the SQL Query -$testQuery = New-SqlQueryDataSet -SQLServer "myServer" -Database "myDB" -Query "SELECT * FROM myTable" -TableName TableSchema +The module includes two classes, the parent class [SqlQueryDataSet] which includes the Tables collections property of child class [SqlQueryTable] objects. -# Create an instance of the [SqlQueryDataSet] class with Database configuration, ConnectionString is autogenerated -$testQuery = New-SqlQueryDataSet -SQLServer "myServer" -Database "myDB" -``` +An instances of [SqlQueryDataSet] manages database information and connections. It's properties and methods manages child [SqlQueryTable] classes, executes queries, and saves the results. -### SQL Express Example +Each instance of the [SqlQueryTable] Class holds the Query configuration and execution results. Each unique query that is added or executed is a separate item in the parent's Tables property. -```powershell -# Configure Database settings for connection -$SqlServer = '(localdb)\MSSQLLocalDB' -$DatabaseName = 'C:\Git\SqlQueryClass\tests\TestDatabase1.mdf' -$ConnectionString = "Data Source={0};AttachDbFilename={1};Integrated Security=True" -f $SqlServer, $DatabaseName - -# Create a new instance of SqlQueryDataSet -$TestQuery = New-SqlQueryDataSet -SQLServer $SqlServer -Database $DatabaseName -ConnectionString $ConnectionString -DisplayResults $true - -# Add and Execute Query to return TableNames and DataBase Version -$TestQuery.ExecuteQuery('DBTables', "SELECT TABLE_NAME, @@VERSION FROM INFORMATION_SCHEMA.TABLES") - -# Displaying the Results of the Query -$TestQuery.Tables[$TestQuery.TableIndex].Result -or -$TestQuery.Tables[$TestQuery.TableNames['DBTables']].Result -or -$index = $TestQuery.TableIndex -$TestQuery.Tables[$index].Result -or -$table = $TestQuery.GetTableFromTableName('DBTables') -$table.Result - -# Changing an existing Table Query and then executing it. -$TestQuery.Tables[$TestQuery.TableIndex].Query = "SELECT * FROM INFORMATION_SCHEMA.TABLES" -$TestQuery.Execute($TestQuery.Tables[$TestQuery.TableIndex]) -$TestQuery.tables[$TestQuery.TableIndex].Result -or -$table = $TestQuery.GetTableFromTableName('DBTables') -$table.Query = "SELECT * FROM INFORMATION_SCHEMA.TABLES" -$table.Parent.Execute() -$table.Result -``` - -### Troubleshooting +An instance Parent Class [SqlQueryDataSet] are created using the New-SqlQueryDataSet() helper CmdLet. -If you encounter issues while using the `SqlQueryClass` Module, ensure that the SQL Server and Database parameters are correctly specified. Verify that the connection string is valid and that the SQL Server is accessible. Check for any errors in the SQL query and make sure that the table name, if specified, exists in the database. +See [API Guide and Class Documentation](api.guide.md) for detailed class and module information. -Examine the object returned from `New-SqlQueryDataSet` +For additional technical information, see: -```powershell -$TestQuery - -SQLServer : (localdb)\MSSQLLocalDB -Database : F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF -ConnectionTimeout : 5 -CommandTimeout : 600 -ConnectionString : Data Source=(localdb)\MSSQLLocalDB;AttachDbFilename=F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF;Integrated Security=True -SQLConnection : -TableIndex : 0 -Tables : {DBTables} -TableNames : {[DBTables, 0]} -DisplayResults : True -KeepAlive : False - -$TestQuery.Tables - -TableIndex : 0 -TableName : DBTables -Query : SELECT * FROM INFORMATION_SCHEMA.TABLES -SQLCommand : System.Data.SqlClient.SqlCommand -SqlDataAdapter : -ResultType : DataTable -Result : {Document, Category, Entity, DocName...} -isDirty : False -QueryFile : -Parent : SqlQueryDataSet - -$TestQuery.Tables.Result - -TABLE_CATALOG TABLE_SCHEMA TABLE_NAME TABLE_TYPE -------------- ------------ ---------- ---------- -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo Document BASE TABLE -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo Category BASE TABLE -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo Entity BASE TABLE -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo DocName BASE TABLE -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo SqlQuery BASE TABLE -F:\DATA\BILLS\PSSCRIPTS\SCANMYBILLS\DATABASE1.MDF dbo SqlQueryParms BASE TABLE -``` +- "Get-Help New-SqlQueryDataSet -Full" +- [New-SqlQueryDataSets.tests.ps1](.\tests\New-SqlQueryDataSets.tests.ps1) in the [.\tests](.\tests) folder has full usage examples used to validate usage +- [Developer and Contributor Guide](contributor.guide.md) ## Folder Structure and Build Management @@ -368,42 +213,44 @@ The the following ModuleTools CmdLets used in the build and maintenance process. ```powershell .\SQLQUERYCLASS -│ .gitignore -│ GitHub_Action_Docs.md -│ LICENSE -│ project.json -│ README.md -│ -├───.vscode -│ settings.json -│ -├───archive -│ -├───dist -│ │ TestResults.xml -│ │ -│ └───SqlQueryClass -│ │ SqlQueryClass.psd1 -│ │ SqlQueryClass.psm1 -│ │ about_SqlQueryClass.help.txt -│ -├───src -│ ├───private -│ │ SqlQueryClass.ps1 -│ │ -│ ├───public -│ │ Dismount-Database.ps1 -│ │ Get-Database.ps1 -│ │ Get-DatabaseTable.ps1 -│ │ Invoke-DatabaseNonQuery.ps1 -│ │ Invoke-DatabaseQuery.ps1 -│ │ Mount-Database.ps1 -│ │ New-SqlQueryDataSet.ps1 -│ │ -│ └───resources -│ about_SqlQueryClass.help.txt -│ -└───tests +| .gitignore +| api.guide.md +| CODE_OF_CONDUCT.md +| contributor.guide.md +| GitHub_Action_Docs.md +| LICENSE +| project.json +| README.md +| wpf.guide.md +| ++---.github +| \---workflows +| tests.yml +| ++---archive ++---dist +| \---SqlQueryClass +| about_SqlQueryClass.help.txt +| SqlQueryClass.psd1 +| SqlQueryClass.psm1 +| ++---src +| +---private +| | SqlQueryClass.ps1 +| | +| +---public +| | Dismount-Database.ps1 +| | Get-Database.ps1 +| | Get-DatabaseTable.ps1 +| | Invoke-DatabaseNonQuery.ps1 +| | Invoke-DatabaseQuery.ps1 +| | Mount-Database.ps1 +| | New-SqlQueryDataSet.ps1 +| | +| \---resources +| about_SqlQueryClass.help.txt +| +\---tests Module.Tests.ps1 New-SqlQueryDataSets.tests.ps1 OutputFiles.Tests.ps1 @@ -424,11 +271,13 @@ The `project.json` file contains all the important details about your module, is ### Root Level and Other Files - .gitignore -- List of file, folder, and wildcard specifications to ignore when publishing to GitHub repository +- CODE_OF_CONDUCT.md -- Standard GitHub code of conduct and standards - GitHub_Action_Docs.md -- How to add GitHub Action WorkFlows to automate CI/CD (Continuous Integration/Continuous Deployment) - LICENSE -- MIT License notice and copyright - project.json -- ModuleTools project configuration file used to build the `SqlQueryClass` module - README.md -- Documentation (this) file for the `SqlQueryClass` module - .vscode\settings.json -- VS Code settings used during `SqlQueryClass` module development +- *.guide.md -- various guides such as api, contributor, wpf ### archive Folder @@ -458,24 +307,22 @@ Run `Invoke-MTTest` to execute the tests. - .\tests\TestDatabase1.mdf -- Sample SQL Express Database File with samples data used in New-SqlQueryDataSets.tests.ps1 - .\tests\TestDatabase1_log.ldf -- Created when using TestDatabase1.mdf -## Contributing +## Join the Conversation -Contributions are welcome! Please fork the repository and submit a pull request with your changes. Ensure that your code adheres to the existing style and includes appropriate tests. +We encourage you to participate in our [Discussions](https://github.com/BrooksV/SqlQueryClass/discussions) section! Whether you have questions, ideas, or just want to chat with other users, Discussions is the place to be. Your feedback and contributions are valuable to us! ## License -This project is licensed under the MIT License. See the LICENSE file for details. +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -[BadgeIOCount]: https://img.shields.io/powershellgallery/dt/SqlQueryClass?label=SqlQueryClass%40PowerShell%20Gallery -[PSGalleryLink]: https://www.powershellgallery.com/packages/SqlQueryClass/ -[WorkFlowStatus]: https://img.shields.io/github/actions/workflow/status/BrooksV/SqlQueryClass/Tests.yml +## Acknowledgements -## SEE ALSO +- [Manjunath Beli](https://github.com/belibug) for the [ModuleTools](https://github.com/belibug/ModuleTools) module used in the build process. +- [Brooks Vaughn](https://github.com/BrooksV) for maintaining the SqlQueryClass module. -```powershell - Get-Help -Name New-SqlQueryDataSet -```powershell +## Contact -## KEYWORDS +For support, inquiries, or feedback, contact Brooks Vaughn at [BrooksV](https://github.com/BrooksV) through one of the following methods: - SQL, Database, Query, SqlQueryDataSet +- **GitHub Issues**: [Open an issue](https://github.com/BrooksV/SqlQueryClass/issues) +- **GitHub Discussions**: [Start a discussion](https://github.com/BrooksV/SqlQueryClass/discussions) diff --git a/api.guide.md b/api.guide.md new file mode 100644 index 0000000..52b0751 --- /dev/null +++ b/api.guide.md @@ -0,0 +1,239 @@ +# API Guide and Class Documentation + +## Table of Contents + +- [Functions](#functions) + - [Dismount-Database](#dismount-database) + - [Get-Database](#get-database) + - [Get-DatabaseTable](#get-database-table) + - [Invoke-DatabaseNonQuery](#invoke-database-non-query) + - [Invoke-DatabaseQuery](#invoke-database-query) + - [Mount-Database](#mount-database) + - [New-SqlQueryDataSet](#new-sql-query-data-set) +- [Classes](#classes) + - [SqlQueryDataSet Parent Class Details](#sql-query-data-set-parent-class-details) + - [Class SqlQueryDataSet Properties](#class-sql-query-data-set-properties) + - [Class SqlQueryDataSet Methods](#class-sql-query-data-set-methods) + - [Child Class SqlQueryTable Properties](#child-class-sql-query-table-properties) + - [Child Class SqlQueryTable Methods](#child-class-sql-query-table-methods) + +## Functions + +```powershell +Get-Command -Module "SqlQueryClass" -Syntax + +- Dismount-Database [[-connectionString] ] [[-Database] ] [-Quiet] +- Get-Database [[-connectionString] ] [[-query] ] [-Quiet] +- Get-DatabaseTable [[-connectionString] ] [[-query] ] [-Quiet] +- Invoke-DatabaseNonQuery [[-connectionString] ] [[-NonQuery] ] [-Quiet] +- Invoke-DatabaseQuery [[-connectionString] ] [[-query] ] [-Quiet] +- Mount-Database [[-connectionString] ] [[-Database] ] [[-DatabaseFilePath] ] [-Quiet] +- New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] +``` + +New-SqlQueryDataSet is the Constructor method for creating an instance of Parent Class [SqlQueryDataSet] and is the main cmdlet. + +To see the examples, type: "Get-Help New-SqlQueryDataSet -Examples" +For more information, type: "Get-Help New-SqlQueryDataSet -Detailed" +For technical information, type: "Get-Help New-SqlQueryDataSet -Full" + +### Dismount-Database + +```powershell +NAME + Dismount-Database +SYNTAX + Dismount-Database [[-connectionString] ] [[-Database] ] [-Quiet] +DESCRIPTION + Detaches a database from the SQL Server. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -Database: The name of the database to detach. + -Quiet: Suppresses output. +``` + +### Get-Database + +```powershell +NAME + Get-Database +SYNTAX + Get-Database [[-connectionString] ] [[-query] ] [-Quiet] +DESCRIPTION + Executes a query against the SQL Server and returns the results. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -query: The SQL query to execute. + -Quiet: Suppresses output. +``` + +### Get-DatabaseTable + +```powershell +NAME + Get-DatabaseTable +SYNTAX + Get-DatabaseTable [[-connectionString] ] [[-query] ] [-Quiet] +DESCRIPTION + Executes a query against the SQL Server and returns the results as a table. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -query: The SQL query to execute. + -Quiet: Suppresses output. +``` + +### Invoke-DatabaseNonQuery + +```powershell +NAME + Invoke-DatabaseNonQuery +SYNTAX + Invoke-DatabaseNonQuery [[-connectionString] ] [[-NonQuery] ] [-Quiet] +DESCRIPTION + Executes a non-query SQL command against the SQL Server. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -NonQuery: The non-query SQL command to execute. + -Quiet: Suppresses output. +``` + +### Invoke-DatabaseQuery + +```powershell +NAME + Invoke-DatabaseQuery +SYNTAX + Invoke-DatabaseQuery [[-connectionString] ] [[-query] ] [-Quiet] +DESCRIPTION + Executes a query against the SQL Server and returns the results. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -query: The SQL query to execute. + -Quiet: Suppresses output. +``` + +### Mount-Database + +```powershell +NAME + Mount-Database +SYNTAX + Mount-Database [[-connectionString] ] [[-Database] ] [[-DatabaseFilePath] ] [-Quiet] +DESCRIPTION + Attaches a database to the SQL Server. +PARAMETERS + -connectionString: The connection string to the SQL Server. + -Database: The name of the database to attach. + -DatabaseFilePath: The file path of the database to attach. + -Quiet: Suppresses output. +``` + +### New-SqlQueryDataSet + +```powershell +NAME + New-SqlQueryDataSet +SYNOPSIS + New-SqlQueryDataSet -- Creates and returns an Object instance of the [SqlQueryDataSet] class configured with or without the specified parameters. +SYNTAX + New-SqlQueryDataSet [[-SQLServer] ] [[-Database] ] [[-ConnectionString] ] [[-Query] ] [[-TableName] ] [[-DisplayResults] ] [] +DESCRIPTION + This function initializes a new instance of the [SqlQueryDataSet] class and the resulting object is configured is based which parameters were specified. + All parameters are optional as the can be configured later using the [SqlQueryDataSet]$object returned when calling $object = New-SqlQueryDataSet + When using $SQLServer and $Database, both must be specified together. The [SqlQueryDataSet] class will auto generate a SQL ConnectionString. + Specifying $ConnectionString overrides auto generation even when $SQLServer and $Database are also specified. + Based on which parameters are passed, this CmdLet will use one of the overloaded class constructors and configure instance settings with the other parameters: + - [SqlQueryDataSet]::new() + - [SqlQueryDataSet]::new(string SQLServer, string Database) + - [SqlQueryDataSet]::new(string SQLServer, string Database, string Query) + Explanation of Parameter Sets: + - **`ServerDatabase`**: This parameter set allows the user to specify the SQL Server and Database separately without needing a full connection string. + - **`ServerDatabaseWithConnectionString`**: This parameter set allows the user to provide both the SQL Server and Database separately, or use a connection string. + - **`ConnectionString`**: This parameter set allows the user to provide a connection string directly. +REMARKS + To see the examples, type: "Get-Help New-SqlQueryDataSet -Examples" + For more information, type: "Get-Help New-SqlQueryDataSet -Detailed" + For technical information, type: "Get-Help New-SqlQueryDataSet -Full" +``` + +## Classes + +### [SqlQueryDataSet] Parent Class Details + +Instances of [SqlQueryDataSet] Parent Class are created using the New-SqlQueryDataSet() helper CmdLet. The object returned is of type [SqlQueryDataSet]. The properties and methods are used to manage and configure database information and connections, manage creation of the Child Class, execute queries, and save the results. Instances of Child Classes are collected in the Tables property of the Parent Class. Tables is a collection of [SqlQueryTable] objects. One is created for every unique query that was added or executed. + +Each instance of the [SqlQueryTable] Class holds the Query configuration and execution results. + +For technical information, see: + +- Get-Help New-SqlQueryDataSet -Full +- New-SqlQueryDataSets.tests.ps1 in the Tests (C:\Git\SqlQueryClass\tests\) folder has full usage examples used to validate usage + +### Class [SqlQueryDataSet] Properties + +Name | Type +----------------- | ---------------------------------------------------------------------- +SQLServer | [System.String] +Database | [System.String] +ConnectionTimeout | [System.Int32] +CommandTimeout | [System.Int32] +ConnectionString | [System.String] +SQLConnection | [System.Object] +TableIndex | [System.Int32] +Tables | [System.Collections.Generic.List`1[[SqlQueryTable, PowerShell Class Assembly, Version=1.0.0.2, Culture=neutral, PublicKeyToken=null]]] +TableNames | [System.Collections.Hashtable] +DisplayResults | [System.Boolean] +KeepAlive | [System.Boolean] + +### Class [SqlQueryDataSet] Methods + +Name | Syntax +-------------------------- | ------------------------------------------------------------- +AddQuery | int AddQuery(string Query) +AddQuery | int AddQuery(string TableName, string Query) +GetTableFromQuery | System.Object GetTableFromQuery(string Query) +GetTableFromTableName | System.Object GetTableFromTableName(string TableName) +BuildOleDbConnectionString | string BuildOleDbConnectionString() +LoadQueryFromFile | void LoadQueryFromFile(string Path) +OpenConnection | void OpenConnection() +CloseConnection | void CloseConnection() +GetSqlCommand | System.Data.SqlClient.SqlCommand GetSqlCommand(string query) +Clear | void Clear() +Execute | System.Object Execute() +Execute | System.Object Execute(SqlQueryTable table) +Execute | System.Object Execute(int TableIndex) +Execute | System.Object Execute(string SqlQuery) +Execute | System.Object Execute(ResultType ResultType) +ExecuteNonQuery | System.Object ExecuteNonQuery(string SqlQuery) +ExecuteQuery | System.Object ExecuteQuery(string SqlQuery) +ExecuteQuery | System.Object ExecuteQuery(string TableName, string SqlQuery) +ExecuteAsDataTable | System.Object ExecuteAsDataTable(string SqlQuery) +ExecuteAsDataAdapter | System.Object ExecuteAsDataAdapter(string SqlQuery) +ExecuteAsDataSet | System.Object ExecuteAsDataSet(string SqlQuery) +ExecuteAsDataRows | System.Object ExecuteAsDataRows(string SqlQuery) +SaveChanges | System.Object SaveChanges() +GetDBTableSchema | System.Object GetDBTableSchema(string TableName) +GetDBTableIndexesV17 | System.Object GetDBTableIndexesV17(string TableName) +GetDBTableIndexes | System.Object GetDBTableIndexes(string TableName) +GetCreateBasicDLL | System.Object GetCreateBasicDLL(string TableName) +GetCreateDDL | System.Object GetCreateDDL(string TableName) +ParseSQLQuery | System.Object ParseSQLQuery(string Query) + +### Child Class [SqlQueryTable] Properties + +Name | Type +-------------- | ----------------- +TableIndex | [System.Int32] +TableName | [System.String] +Query | [System.String] +SQLCommand | [System.Object] +SqlDataAdapter | [System.Object] +ResultType | [ResultType] +Result | [System.Object] +isDirty | [System.Boolean] +QueryFile | [System.String] +Parent | [SqlQueryDataSet] + +### Child Class [SqlQueryTable] Methods + +Class Has No Methods diff --git a/contributor.guide.md b/contributor.guide.md new file mode 100644 index 0000000..33a1a95 --- /dev/null +++ b/contributor.guide.md @@ -0,0 +1,127 @@ +# Developer and Contributor Guide + +## Table of Contents + +- [Setup](#setup) +- [Source Files used in the Module](#source-files-used-in-the-module) +- [Module Build Process](#module-build-process) +- [Publishing `SqlQueryClass` Module to GitHub](#publishing-sqlqueryclass-module-to-github) +- [Code Review and Feedback](#code-review-and-feedback) +- [Merge the Pull Request](#merge-the-pull-request) +- [Cleanup](#cleanup) +- [Publishing `SqlQueryClass` Module to PowerShell Gallery](#publishing-sqlqueryclass-module-to-powershell-gallery) + +## Setup + +- Uses SQL Express but should work with other SQL Databases with proper connection strings and credentials +- Requires VS Code +- For Contributors, Fork the [SqlQueryClass](https://github.com/BrooksV/SqlQueryClass) repository +- Clone the repository or fork to local pc. I like using c:\git as my local repository folder. Subfolder $ProjectName will be created with the GitHub repository contents +- Install [Manjunath Beli's ModuleTools](https://github.com/belibug/ModuleTools) module as the module build process uses ModuleTools + + ```powershell + Find-Module -Name ModuleTools | Install-Module -Scope CurrentUser -Verbose + ``` + +- Note that a sample SQL Express database file (.\tests\TestDatabase1.mdf) is included for pester tests. The database configuration is set in .\tests\TestDatabase1.parameters.psd1 + +## Source Files used in the Module + +- Public functions that are exported, are separate files in the .\src\public folder. +- Private functions that are local to the Module, are separate files in the .\src\private folder. +- - Class Definitions and Enums are not accessible outside of the Module and cannot be accessed directly like Public Functions are. This is a PowerShell limitation. +- - - Classes [SqlQueryDataSet] and [SqlQueryDataSetParms] and enum ResultType used in the Module are defined in file .\src\private\SqlQueryClass.ps1 file. The classes have properties and methods used to maintain a Database connections and result sets making it useful WPF Data binding. +- Resources are files and folders in the .\src\resources folder that needs to be included with the Manifest and Module + +## Module Build Process + +1. Create a local branch for your changes. + +- - Use descriptive name that reflects the type of changes for branch for example features/database-table-access + + ```powershell + git checkout -b features/database-table-access + ``` + +1. Update the build version using Update-MTModuleVersion (Find-Module -Name ModuleTools). +1. Commit your changes to the branch. +1. Run the Pester Tests using Invoke-MTTest (Find-Module -Name ModuleTools). +1. Build the Module output using Invoke-MTBuild -Verbose (Find-Module -Name ModuleTools). + + ```powershell + Invoke-MTBuild -Verbose + ``` + +- - Outputs to the .\dist\SqlQueryClass folder +- - Combines the file contents of the files in Public and Private folder into .\dist\SqlQueryClass\SqlQueryClass.psd1 and exports the Public Functions +- - Generates the .\dist\SqlQueryClass\SqlQueryClass.psd1 Manifest file from the settings in .\project.json +- - Resources (.\src\resources) folder content is copied to .\dist\SqlQueryClass folder +- Run the Pester Teats using Invoke-MTTest (Find-Module -Name ModuleTools) + +1. Make corrections, repeat the build process. +1. For Contributors: + - Create an Issue if one does not exist that addresses the proposed changes. + - Upstream your branch. + - Create a Pull request. + +## Publishing `SqlQueryClass` Module to GitHub + +1. Stage and Commit Your Changes + + ```powershell + git add . + git commit -m "Implemented database and table access functions" + ``` + +1. Update remote repository with branch changes + + ```powershell + # List status of remote repository + git branch -r + # Create Branch on remote repository if needed + # git push --set-upstream origin features/database-table-access + # Push branch changes to remote branch in repository + git push origin features/database-table-access + ``` + +1. Create a Pull Request on remote repository + - Go to [SqlQueryClass GitHub repository](https://github.com/BrooksV/SqlQueryClass) + - Click on "Compare & pull request" for your branch + - Provide a meaningful title and description for the PR + - Select the base branch (main) to merge into + - Click "Create pull request" + +## Code Review and Feedback + +- Engage with Repository Owner or collaborators to review the PR +- Address any feedback or requested changes by making additional commits to your branch and pushing them to the remote branch +- Ensure the PR passes any automated tests or checks + +## Merge the Pull Request + +- Once the PR is approved and all checks pass, you can merge it into the main branch +- You can either use the "Merge pull request" button on GitHub or merge it locally and push the changes + +## Cleanup + +- After merging, you can delete the feature branch from the remote repository to keep it clean + +```powershell +git push origin --delete features/database-table-access +``` + +- Optionally, delete the local branch + +```powershell +git branch -d features/database-table-access +``` + +These steps will ensure your changes are integrated into the main branch and your repository remains organized. + +## Publishing `SqlQueryClass` Module to PowerShell Gallery + +```powershell +$data = Get-MTProjectInfo +$ApiKey = "your-api-key-here" +Publish-Module -Path $data.OutputModuleDir -NuGetApiKey $ApiKey -Repository PSGallery +``` diff --git a/git_cheatsheet.md b/git_cheatsheet.md deleted file mode 100644 index 2035ac7..0000000 --- a/git_cheatsheet.md +++ /dev/null @@ -1,425 +0,0 @@ -# CheetSheet - -& "C:\Program Files (x86)\Info Keep\info keep.exe" - -Photography Co-worker [Kevin Hecht](mailto://kevin.a.hecht@pwc.com) - -## To Publish Module to PowerShell Gallery - -```powershell -Publish-Module -Path -NuGetApiKey -Repository PSGallery - -Publish-Module -Path "C:\Git\SqlQueryClass\dist\SqlQueryClass" -NuGetApiKey "" -Repository PSGallery - -Find-Module -Name SqlQueryClass | Install-Module -Scope CurrentUser -AcceptLicense - -Find-Module -Name SqlQueryClass | FL - -Name : SqlQueryClass -Version : 0.1.0 -Type : Module -Description : Module that create an instance of a PowerShell class which is used to execute SQL Queries and manages output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result object. -Author : Brooks Vaughn -CompanyName : BrooksV -Copyright : (c) Brooks Vaughn. All rights reserved. -PublishedDate : 2/6/2025 3:43:39 AM -InstalledDate : -UpdatedDate : -LicenseUri : https://github.com/BrooksV/SqlQueryClass/blob/main/LICENSE -ProjectUri : https://github.com/BrooksV/SqlQueryClass -IconUri : -Tags : {PowerShell, Database, SQL, SQLServer…} -Includes : {[RoleCapability, System.Object[]], [DscResource, System.Object[]], [Cmdlet, System.Object[]], [Workflow, System.Object[]]…} -PowerShellGetFormatVersion : -ReleaseNotes : -Dependencies : {} -RepositorySourceLocation : https://www.powershellgallery.com/api/v2 -Repository : PSGallery -PackageManagementProvider : NuGet -AdditionalMetadata : @{summary=Module that create an instance of a PowerShell class which is used to execute SQL Queries and manages output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result object.; - ItemType=Module; IsPrerelease=false; PackageManagementProvider=NuGet; NormalizedVersion=0.1.0; SourceName=PSGallery; tags=PowerShell Database SQL SQLServer SQLQuery DataAdapter DataSet DataTable - PSModule; description=Module that create an instance of a PowerShell class which is used to execute SQL Queries and manages output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result - object.; Authors=Brooks Vaughn; versionDownloadCount=0; GUID=8375edbe-fb0f-4cb6-acb0-9964b45725c0; lastUpdated=2/6/2025 3:43:39 AM -05:00; requireLicenseAcceptance=False; downloadCount=0; - isLatestVersion=True; CompanyName=Unknown; Functions=New-SqlQueryDataSet; FileList=SqlQueryClass.nuspec|about_SqlQueryClass.help.txt|SqlQueryClass.psd1|SqlQueryClass.psm1; - PowerShellHostVersion=5.1; created=2/6/2025 3:43:39 AM -05:00; isAbsoluteLatestVersion=True; copyright=(c) Brooks Vaughn. All rights reserved.; packageSize=15464; developmentDependency=False; - updated=2025-02-06T03:43:39Z; published=2/6/2025 3:43:39 AM -05:00} -``` - -## Code Signing - -Get-ChildItem -Path Cert:\CurrentUser -Recurse | FL -Get-ChildItem -Path Cert:\CurrentUser\My -CodeSigningCert -Get-ChildItem -Path Cert:\LocalMachine -Recurse | FL - -## git config commands - -- ps.readinglist.md -- Quick Reference Reading list of helpful PowerShell sites, articles, and documents - -### Support for Long Paths - -git config --system core.longpaths true - -#### git remote urls - -git remote -v - -## User Config - -### To Set your username - -```powershell -git config --global user.name "FIRST_NAME LAST_NAME" -``` - -### To Set your email address - -```powershell -git config --global user.email "MY_NAME@example.com" - -git config --global user.name "Brooks Vaughn" -git config --global user.email "18422308+BrooksV@users.noreply.github.com" - -git config --worktree user.name "Brooks Vaughn" -git config --global user.email "18422308+BrooksV@users.noreply.github.com" -``` - -### Check configuration for your user - -$ cat $HOME/.gitconfig - -## Proxy Config - -### Get system value - -```powershell -git config --system --get https.proxy -git config --system --get http.proxy -``` - -### Get global value - -```powershell -git config --global --get https.proxy -git config --global --get http.proxy -``` - -### Unset system value - -```powershell -git config --system --unset https.proxy -git config --system --unset http.proxy -``` - -### Unset global value - -```powershell -git config --global --unset https.proxy -git config --global --unset http.proxy -``` - -## Proxy Config using Environment Variables - -Your proxy could also be set as an environment variable. Check if your environment has any of the env variables http_proxy or https_proxy set up and unset them. Examples of how to set up: - -### Linux - -```bash -export http_proxy=http://proxy:8080 -export https_proxy=https://proxy:8443 -``` - -### Windows - -```powershell -set http_proxy http://proxy:8080 -set https_proxy https://proxy:8443 -``` - -## SSL Config - -```powershell -git config --global http.sslVerify -git config --global http.sslVerify true -``` - -### Repro Clone SSL Errors - -```powershell -SSL_VERIFY=false -git config --global http.sslVerify false -``` - -My agents are running as Network Service too but that wasn't really a problem to use user level config. Here is what I did: -1.Save all the necessary certificates in folder %systemroot%\ServiceProfiles\NetworkService\.gitcerts\. -2.Create a file at %systemroot%\ServiceProfiles\NetworkService\.gitconfig with the following content: - -[http "https://tfs.com/"](http "https://tfs.com/") - -$sslCAInfo = ~/.gitcerts/certificate.pem - -[adding-a-corporate-or-self-signed-certificate-authority-to-git-exes-store](https://blogs.msdn.microsoft.com/phkelley/2014/01/20/adding-a-corporate-or-self-signed-certificate-authority-to-git-exes-store/) - -git config --global http.sslBackend schannel - -[how-to-make-git-work-with-self-signed-ssl-certificates-on-tfs2018](https://www.benday.com/2017/12/15/how-to-make-git-work-with-self-signed-ssl-certificates-on-tfs2018/) -[fix-git-self-signed-certificate-in-certificate-chain-on-windows](https://mattferderer.com/fix-git-self-signed-certificate-in-certificate-chain-on-windows) - -## Git Repo and Branch Commands - -### Reset Local Master - -git fetch origin master -git checkout master -git reset --hard origin/master -git reset origin/master --hard -git pull origin master - -### Reset Local Main - -git fetch origin main -git checkout main -git reset --hard origin/main -git pull origin main - -If you want to create a new branch to retain commits you create, you may do so (now or later) by using -c with the switch command. - -```powershell -Example: - git switch -c - -Or undo this operation with: - git switch -? -``` - -## Status and Info Commands - -```powershell -git status -git log -git branch --all -git branch features/ - -git fetch origin -git fetch origin master -git checkout master -git pull origin master -git checkout features/ -git merge branch master -git status -git log -git push - -git pull -git branch -a -``` - -## To Create Branch from Master - -```powershell -git fetch origin master -git checkout master -git pull origin master -git checkout -b features/??? -git push --set-upstream origin features/??? -git checkout features/??? -``` - -### Create local branch - -```powershell -git checkout -b features/ -git status -git add foo.txt -git commit -m "" -git commit -a -m "" ## ? -git push -``` - -### Create Branch on origin (UpStream) to Repository - -```powershell -git push --set-upstream origin features/ -``` - -### To sync local master - -```powershell -git checkout master -git pull - -git checkout features/readme-updates -git merge master ???? -``` - -## Notes - -Origin is the plcae where the branch was cloned from - -```powershell -git remote add -git add -p -git log --online - -npm config set strict-ssl false -``` - -## Git Merging commands - -```powershell -git merge branch master -git status -git log -git push - -git config --get --local core.filemode -false - -git config --local --list -``` - -## Commits - -```powershell -git add yaml\???.yml -git commit -m "???" -git commit -a -m "" ## ? -git push -git merge --abort -git branch -a --sort=-committerdate --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(color:red)%(objectname:short)%(color:reset) - %(contents:subject) - %(authorname) (%(color:green)%(committerdate:relative)%(color:reset))' -(git reflog > reflog.md) | Invoke-Item -git reflog | Select-String -``` - -## Explanation of what each of those Git commands do - -### `git add yaml???.yml` - -- **Description**: Adds files matching the pattern `yaml???.yml` to the staging area. -- **Wildcard**: The `???` matches exactly three characters, so this would match files like `yaml123.yml` or `yamlABC.yml`. -- **Example**: `git add yaml123.yml` or `git add yamlABC.yml`. - -### `git commit -m "???"` - -- **Description**: Commits the staged changes to the repository with a commit message `"???"`. -- **Purpose**: The message `"???"` is a placeholder and should be replaced with a meaningful description of the changes. -- **Example**: `git commit -m "Added new YAML configuration files"`. - -### `git commit -a -m ""` - -- **Description**: Commits all changes to tracked files (bypassing the staging area) with an empty commit message. -- **Purpose**: This is unusual because an empty commit message is generally not recommended. It's better to provide a meaningful commit message. -- **Example**: `git commit -a -m "Updated configuration files"`. - -### `git push` - -- **Description**: Pushes the committed changes from your local repository to the remote repository. -- **Purpose**: Sends your local commits to the remote repository (e.g., GitHub). -- **Example**: `git push origin master`. - -### `git merge --abort` - -- **Description**: Aborts the current merge process and attempts to revert the repository back to the state before the merge began. -- **Purpose**: Used when a merge conflict occurs, and you decide to cancel the merge and resolve conflicts later. -- **Example**: `git merge --abort` while in the middle of a conflicting merge. - -### `git branch -a --sort=-committerdate --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(color:red)%(objectname:short)%(color:reset) - %(contents:subject) - %(authorname) (%(color:green)%(committerdate:relative)%(color:reset))'` - -- **Description**: Lists all branches sorted by the most recent commit date, with a custom format for the output. -- **Purpose**: Provides a detailed, color-coded list of branches, showing which branch is current (HEAD), commit hash, subject of the commit, author name, and the date relative to now. -- **Example**: `git branch -a --sort=-committerdate --format='...'`. - -### `(git reflog > reflog.md) | Invoke-Item` - -- **Description**: Redirects the output of `git reflog` to a file named `reflog.md` and opens the file. -- **Purpose**: Records the reflog (history of changes) into a markdown file and opens it in the default text editor. -- **Example**: `(git reflog > reflog.md) | Invoke-Item`. - -### `git reflog | Select-String` - -- **Description**: Displays the reflog and filters the results using `Select-String`. -- **Purpose**: Allows you to search the reflog for specific patterns or keywords. -- **Example**: `git reflog | Select-String "commit"` to find entries related to commits. - -These commands cover a range of Git operations, from staging and committing changes to managing branches and searching through logs. Let me know if you have any more questions or need further details! - -## Git Command docs - -```powershell -git remote add upstream -git fetch upstream -git rebase upstream/master -git push origin master --force -``` - -## Explanation of what each of those Git commands does - -### `git remote add upstream` - -This command adds a new remote repository, typically the original repository from which you forked your project. - -```bash -git remote add upstream -``` - -- **Purpose**: To add a reference to the original repository (upstream) so you can pull updates from it. -- **Example**: If you forked a repository on GitHub, you would use the URL of the original repository. - -### `git fetch upstream` - -This command fetches updates from the `upstream` remote repository. - -```bash -git fetch upstream -``` - -- **Purpose**: To get the latest changes from the upstream repository without merging them into your working branch. -- **Example**: This updates your local copy of the remote branches from the upstream repository. - -### `git rebase upstream/master` - -This command rebases your current branch on top of the `master` branch from the `upstream` repository. - -```bash -git rebase upstream/master -``` - -- **Purpose**: To integrate changes from the upstream repository into your current branch by applying your local commits on top of the upstream/master branch. -- **Example**: Useful for keeping your forked repository up-to-date with the original repository. - -### `git push origin master --force` - -This command pushes your local `master` branch to the remote repository (origin) with force. - -```bash -git push origin master --force -``` - -- **Purpose**: To overwrite the remote `master` branch with your local changes, even if it results in non-fast-forward updates. -- **Example**: Use with caution as it can overwrite changes in the remote repository that others may be relying on. - -## 2025-02-05 22:59:55 - -```powershell -git pull origin main - -git checkout -b features/readme-updates -git status - -git commit -m "" - -git commit -a -m "Updated SQL query class and added error handling" - -git push -``` - -```powershell -``` - -```powershell -``` - -```powershell -``` - -```powershell -``` diff --git a/project.json b/project.json index ca8fa4d..4380059 100644 --- a/project.json +++ b/project.json @@ -1,7 +1,7 @@ { "ProjectName": "SqlQueryClass", - "Description": "Module that create an instance of a PowerShell class which is used to execute SQL Queries and manages output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result object.", - "Version": "0.1.1", + "Description": "The SqlQueryClass module provides a set of functions and cmdlets for working with SQL databases. It includes functionality for connecting, executing SQL queries, and managing output as DataTable, DataAdapter, DataSet, SqlReader, or NonQuery result objects.", + "Version": "0.1.2", "Manifest": { "Author": "Brooks Vaughn", "PowerShellHostVersion": "5.1", diff --git a/src/private/SqlQueryClass.ps1 b/src/private/SqlQueryClass.ps1 index c6947ed..1e580ca 100644 --- a/src/private/SqlQueryClass.ps1 +++ b/src/private/SqlQueryClass.ps1 @@ -74,7 +74,7 @@ $TestQuery.Database = $DatabaseName $TestQuery.ConnectionString = $ConnectionString $TestQuery.DisplayResults = $true -$TestQuery.AddQuery("SELECT @@VERSION FROM INFORMATION_SCHEMA.TABLES", 'Version') +$TestQuery.AddQuery('Version', "SELECT @@VERSION FROM INFORMATION_SCHEMA.TABLES") $TestQuery.Tables[0].Query = "SELECT TABLE_NAME, @@VERSION FROM INFORMATION_SCHEMA.TABLES" $TestQuery.Execute() @@ -104,7 +104,7 @@ $TestQuery $TestQuery -AddQuery Method int AddQuery(string Query), int AddQuery(string Query, string TableName) +AddQuery Method int AddQuery(string Query), int AddQuery(string TableName, string Query) BuildOleDbConnectionString Method string BuildOleDbConnectionString() Clear Method void Clear() CloseConnection Method void CloseConnection() @@ -246,7 +246,7 @@ PS C:\Git\SqlQueryEditor> $TestQuery | GM Name MemberType Definition ---- ---------- ---------- -AddQuery Method int AddQuery(string Query), int AddQuery(string Query, string TableName) +AddQuery Method int AddQuery(string Query), int AddQuery(string TableName, string Query) BuildOleDbConnectionString Method string BuildOleDbConnectionString() Clear Method void Clear() CloseConnection Method void CloseConnection() @@ -368,9 +368,9 @@ class SqlQueryDataSet { # Methods to Add New Table for Query and Results [int] AddQuery([String]$Query) { - Return $This.AddQuery($Query, [String]::Empty) + Return $This.AddQuery([String]::Empty, $Query) } - [int] AddQuery([String]$Query, [String]$TableName) { + [int] AddQuery([String]$TableName, [String]$Query) { If (-not $this.Tables) { $this.Tables = [System.Collections.Generic.List[SqlQueryTable]]::new() } @@ -667,7 +667,7 @@ class SqlQueryDataSet { [Object] ExecuteQuery([String]$TableName, [String]$SqlQuery) { If ($SqlQuery) { - $This.TableIndex = $This.AddQuery($SqlQuery, $TableName) + $This.TableIndex = $This.AddQuery($TableName, $SqlQuery) } $table = $This.Tables[$This.TableIndex] $table.ResultType = [ResultType]::DataTable diff --git a/src/public/New-SqlQueryDataSet.ps1 b/src/public/New-SqlQueryDataSet.ps1 index 00eda08..90da3cb 100644 --- a/src/public/New-SqlQueryDataSet.ps1 +++ b/src/public/New-SqlQueryDataSet.ps1 @@ -92,7 +92,7 @@ function New-SqlQueryDataSet { } if (-not [string]::IsNullOrEmpty($Query)) { if (-not [string]::IsNullOrEmpty($TableName)) { - [void]$instance.AddQuery($Query, $TableName) + [void]$instance.AddQuery($TableName, $Query) } else { [void]$instance.AddQuery($Query) } diff --git a/tests/TestDatabase1.mdf b/tests/TestDatabase1.mdf new file mode 100644 index 0000000..5db30b6 Binary files /dev/null and b/tests/TestDatabase1.mdf differ diff --git a/tests/TestDatabase1_log.ldf b/tests/TestDatabase1_log.ldf new file mode 100644 index 0000000..0da2156 Binary files /dev/null and b/tests/TestDatabase1_log.ldf differ diff --git a/wpf.guide.md b/wpf.guide.md new file mode 100644 index 0000000..95b0435 --- /dev/null +++ b/wpf.guide.md @@ -0,0 +1,263 @@ +# WPF Usage Guide + +## Table of Contents + +- [Introduction](#introduction) +- [Prerequisites](#prerequisites) +- [Setting Up the Environment](#setting-up-the-environment) +- [Creating the WPF Application](#creating-the-wpf-application) + - [XAML Layout](#xaml-layout) + - [PowerShell Code-Behind Example](#powershell-code-behind-example) +- [Binding Data to the DataGrid](#binding-data-to-the-datagrid) + - [Creating the SqlQueryDataSet Instance](#creating-the-sqlquerydataset-instance) + - [Executing the Query](#executing-the-query) + - [Binding the DataTable to the DataGrid](#binding-the-datatable-to-the-datagrid) +- [Handling CRUD Operations](#handling-crud-operations) + - [Adding New Rows](#adding-new-rows) + - [Updating Existing Rows](#updating-existing-rows) + - [Deleting Rows](#deleting-rows) + - [Saving Changes](#saving-changes) +- [Advanced Topics](#advanced-topics) + - [Handling Complex Queries](#handling-complex-queries) + - [Using Multiple DataGrids](#using-multiple-datagrids) + - [Customizing DataGrid Columns](#customizing-datagrid-columns) +- [Troubleshooting](#troubleshooting) +- [Conclusion](#conclusion) + +## Introduction + +This guide provides detailed instructions on how to use the `SqlQueryClass` module to bind the `SqlQueryTable` class result as a `DataTable` to a WPF `DataGrid` component. This allows for seamless integration of SQL query results into a WPF application, enabling data manipulation and display. + +## Prerequisites + +Before you begin, ensure you have the following: + +- PowerShell Version 5.1 or higher +- A text or code editor of you choice +- - PowerShell scripts and even XAML can created and edited with any text or code editor +- - PowerShell_ISE comes with most every Windows OS +- - VS Code or Visual Studio are also very good for serious development +- - - Helps with cloning repository and PS Code development +- - - Visual Studio comes with Blend which is a WPF GUI based editor +- Git for version control +- Basic knowledge of WPF and XAML +- SQL Server or SQL Express installed +- The `SqlQueryClass` module installed +- The example code below uses tests configuration and sample SQL Express database from [GitHub `SqlQueryClass` repository](https://github.com/BrooksV/SqlQueryClass) +- - Clone the Repository (using git commands, VS Code, or Visual Studio) to C:\Git folder to maintain compatibility with the sample and test data +- - Can also be done downloading the repository as a zip file + +## Setting Up the Environment + +1. Install the `SqlQueryClass` module if you haven't already: + + ```powershell + Install-Module -Name SqlQueryClass -Repository PSGallery -Scope CurrentUser + ``` + +2. Create a new PowerShell project in VS Code or Visual Studio. + +- Visual Studio's WPF project is a .Net C# project and is great for creating the XAML file that can be used with PowerShell or with C#. +- There are a few differences in the XAML such as PowerShell does not support Click and other OnEvent handlers and need to be added in Code-Behind. +- The advantage is it's PowerShell which is much easier to learn, use, and edit than a traditional .Net C# application development, test, and release process. +- PowerShell WPF is great for adding simple to very complex GUI interfaces and applications for your scripts. + +## Creating the WPF Application + +### XAML Layout + +Define the layout of your WPF application in the `MainWindow.xaml` file. Add a `DataGrid` component to display the data. + +The [PowerShell Code-Behind Example](#powershell-code-behind-example) uses the XAML in-line to avoid having to read from disk. + +```xml + + + + +