linq2db/docs

Documentation sources and build scripts

docs's Issues

Add automatic documentation deployment

Add automatic build and deployment of documentation using Azure DevOps to https://github.com/linq2db/linq2db.github.io on master branch commit

Documentation

Ok, let's speak about our Achilles' heel - documentation.
To be honest everything is awful, only documentation is start page & a little bit of wiki. We should work on it!
My suggestion is to build documentation using DocFX, things to be done:

• Write XML documentation
• Examine DocFX & prepare contributors' guide
• Configure CI to build documentation on each commit
• Find out how & where documentation can be hosted

Volunteer needed.

XML documentation tasks

If you are going to document any section please write comment below an we'll mark that it is in process:

• LinqToDB.Data.DataConnection : .ctor region

• LinqToDB.Data.DataConnection : public properties region

• LinqToDB.Data.DataConnection : configuration region

• LinqToDB.Data.DataConnection : connection region

• LinqToDB.Data.DataConnection : command region

• LinqToDB.Data.DataConnection : transaction region

• LinqToDB.Data.DataConnection : MappingSchema region

• LinqToDB.Data.DataConnection : GetTable methods

• LinqToDB.Data.DataConnectionExtensions : SetCommand region

• LinqToDB.Data.DataConnectionExtensions : Query* regions

• LinqToDB.Data.DataConnectionExtensions : Execute* regions

• LinqToDB.Data.DataConnectionExtensions : BulkCopy region

• LinqToDB.Data.DataConnectionExtensions : Merge region (@MaceWindu)

• LinqToDB.IDataContext

• LinqToDB.DataExtensions: Table Helpers region

• LinqToDB.DataExtensions: Insert region

• LinqToDB.DataExtensions: InsertOrReplace region

• LinqToDB.DataExtensions: InsertWithIdentity region

• LinqToDB.DataExtensions: Update region

• LinqToDB.DataExtensions: Delete region

• LinqToDB.DataExtensions: DDL Operations region

• LinqToDB.LinqExtensions: Table Helpers region

• LinqToDB.LinqExtensions: LoadWith region

• LinqToDB.LinqExtensions: Scalar Select region

• LinqToDB.LinqExtensions: Delete region

• LinqToDB.LinqExtensions: Update region

• LinqToDB.LinqExtensions: Insert region

• LinqToDB.LinqExtensions: InsertOrUpdate region

• LinqToDB.LinqExtensions: DDL Operations region

• LinqToDB.LinqExtensions: Take/Skip/ElementAt region

• LinqToDB.LinqExtensions: Having region

• LinqToDB.LinqExtensions: IOrderedQueryable region

• LinqToDB.Common.Configuration

• BulkCopy: LinqToDB.Data.BulkCopyType, LinqToDB.Data.BulkCopyOptions

• LinqToDB.ExpressionMethodAttribute

• LinqToDB.Sql.TableFunctionAttribute

• LinqToDB.Sql.TableExpressionAttribute

• LinqToDB.Sql.PropertyAttribute

• LinqToDB.Sql.GroupBy

• LinqToDB.Sql.FunctionAttribute

• LinqToDB.Sql.ExpressionAttribute

• LinqToDB.Sql.EnumAttribute

• LinqToDB.Sql math functions region

• LinqToDB.Sql string, text, guid and binary functions regions

• LinqToDB.Sql datetime functions region

• LinqToDB.Sql convert functions region

• LinqToDB.Sql common functions region

• LinqToDB.ServiceModel.SoapDataContext

• LinqToDB.ServiceModel.ServiceModelDataContext

• LinqToDB.Mapping.TableAttribute

• LinqToDB.Mapping.StoredProcedure (sic!)

• LinqToDB.Mapping.SequenceNameAttribute

• LinqToDB.Mapping.ScalarTypeAttribute

• LinqToDB.Mapping.Relationship

• LinqToDB.Mapping.PrimaryKeyAttribute

• LinqToDB.Mapping.NullableAttribute

• LinqToDB.Mapping.NotNullAttribute

• LinqToDB.Mapping.NotColumnAttribute

• LinqToDB.Mapping.MapValueAttribute

• LinqToDB.Mapping.MapValue

• LinqToDB.Mapping.AssociationAttribute

• LinqToDB.Mapping.ColumnAliasAttribute

• LinqToDB.Mapping.ColumnAttribute

• LinqToDB.Mapping.DataTypeAttribute

• LinqToDB.Mapping.IdentityAttribute

• LinqToDB.Mapping.InheritanceMappingAttribute

• LinqToDB.Mapping.MappingSchema: constructors

• LinqToDB.Mapping.MappingSchema: ValueToSqlConverter region

• LinqToDB.Mapping.MappingSchema: Default Values region

• LinqToDB.Mapping.MappingSchema: CanBeNull region

• LinqToDB.Mapping.MappingSchema: Convert region

• LinqToDB.Mapping.MappingSchema: DefaultMappingSchema region

• LinqToDB.Mapping.MappingSchema: Scalar Types region

• LinqToDB.Mapping.EntityDescriptor

• LinqToDB.Mapping.ColumnDescriptor

• LinqToDB.Mapping.AssociationDescriptor

• LinqToDB.Mapping.InheritanceMapping

• LinqToDB.Linq.Expressions: MapMember region

• LinqToDB.Linq.Expressions: Sql specific region

• LinqToDB.Linq.Expressions: Provider specific functions region

Documentation on .net core doesn't work / more details

I just set up a .net core 2.1.x MVC project in VS2017 and tried with the documentation to get started and got a syntax error and some issues:

yield does not exist in context / Invalid token "break;

Steps to reproduce

public IEnumerable<IDataProviderSettings> DataProviders => yield break;

This works:

public IEnumerable<IDataProviderSettings> DataProviders => Enumerable.Empty<IDataProviderSettings>();

Also the docs are really thin. Where to I put also DataConnection.DefaultSettings = new MySettings();?

I assume in MVC apps in Startup.cs and I also don't know if it's supposed to be implemented like that anymore (?). Could you give in code examples also the entire file, so one can see exactly what you imported and so forth (like MS docs).

Thanks.

Environment details

linq2db version: 1.10.0
Database Server: MySql 5.7
Operating system: E.g. Windows 10
Framework version: .NET Core 2.1.x
Visual Studio: 2017

Load Entity-DB mapping and Entity attributes from XML file (vs. POCO attributes)

Hi Igor,

I am preparing to use linq2db in a project. The Wiki gives an example of how to annotate a POCO class to build the Entity-DB mapping necessary to generate usable SQL for LINQ expression tree. However, I would like to load these attributes from an XML file instead - to avoid mixing DB and Entity specification. This will leave the POCO code clean. But linq2db will still have what it needs to do the SQL generation.

LinqToDB.Metadata.XmlAttributeReader looks like it will fit the bill, and there is sample XML in the Tests.Metada.XmlReaderTests.cs file. However, I'm not confident that I could write up XML that would work first-time with linq2db. I am also not certain how to apply the loaded mapping so that linq2db uses it (instead of trying to use reflection to analyse the POCO types).

Would you have a minute to post: a) a sample XML file that shows the key attributes that might be applied to a POCO class and its members; b) how to initialize linq2db so that this model is used, and not the one generated by reflection - which won't work if I don't annotate the POCO class with the various attributes.

I did notice that you also have a tool to generate the annotated POCO classes from a model (DB or otherwise). However, again, my hope is to keep the entity-DB mapping and entity attributes in an XML file, to keep the POCO sparse. Thank you!

Marc

Create provider-specific issues FAQ

Candidates for documenting:

• linq2db/linq2db#856

How to choose a dialect of Oracle 11g?

How to choose a dialect of Oracle 11g?
After migration from 2.9.8 to 3.1.3 'Take ()' expression does not work for Oracle 11g with provider name "Oracle".
When I changed the provider name to "Oracle.Managed" the version was selected correctly.

Remove documentation sources and build from linq2db repository

Remove articles and build/deploy scripts from linq2db repository

Integrate examples into documentation

We need to decide what to do with existing https://github.com/linq2db/examples repository

Update azure pipelines integration to not fail on PRs

Now pipelines build for PR fails due to attempt to use github PAT from PR, see #24 failures

Migrate non-essential .md files from other repositories

Documentation md files from other repositories should be moved to articles. E.g. t4 readme.md

hi,please vs entityframe work core

hi,please vs entityframe work core

Fix xmldoc build errors

[19-05-25 01:47:31.608]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates](api/LinqToDB.Data.BulkCopyOptions.yml)The value of property 'name' in uid 'MaxBatchSize' is not string
[19-05-25 01:47:31.611]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates](api/LinqToDB.EntityFrameworkCore.LinqToDBForEFToolsImplDefault.yml)The value of property 'name' in uid 'LinqToDB.EntityFrameworkCore.EFCoreMetadataReader' is not string
[19-05-25 01:47:31.616]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates](api/LinqToDB.Common.Configuration.Linq.yml)The value of property 'name' in uid 'LinqToDB.Linq.Query`1.ClearCache' is not string
[19-05-25 01:47:31.617]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates](api/LinqToDB.Mapping.MappingSchema.yml)The value of property 'name' in uid 'System.Data.Linq.Mapping' is not string
[19-05-25 01:47:31.617]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates](api/LinqToDB.Mapping.MappingSchema.yml)The value of property 'name' in uid 'Microsoft.SqlServer.Server' is not string

Wcf service transaction

If I use your WCF Service, how is it like with transactions. Is the transaction commited if the using of the service context ends? What if the connection is closed before the using block ends (error case) , is the query executed?

Add documentation about temp tables and ExpressionMethod

Hi!

It would be great to add documentation about:

1. Temp tables (CreateTempTable method)
2. ExpressionMethod (blog)

Add new documentation tree

We need to create new documentation structure (without actual documentation yet) and then fill new issue for each missing article

Fail build on docfx warnings

First we need to fix existing warnings (#6)

Migrate documentation issues to this repository

Review existing issues in other repositories and move them here if they are related to documentation

• linq2db issues
• linq2db.LINQPad issues (nothing to move)
• linq2db.EntityFrameworkCore issues (nothing to move)
• examples issues
• LinqToDB.Identity issues (nothing to move)
• IdentityServer4.LinqToDB issues (nothing to move)

Switch to docfx branch as xml-doc API source for all submodules

Need to create/actualize this branch for all imported submodules first

Create wiki article about mappings configuration and how to support mappings from other ORM/custom mapping sources

How to use DataConnectionExtensions.ExecuteProc()?

I am trying to get hang of linq2db, but can't find any real examples.
for example I am trying to run a stored procedure (see below), however it does not seem to fire.

int x = DataConnectionExtensions.ExecuteProc(connection, "spName", DataParameter.Varchar("whateverParamName", "whateverParamValue"))
I am passing the parameters the right way?
Like sql, should it be EXEC spName @whateverParamName or is it ok
When I specify dataparameter do I need to specify with @? like @whateverParamName (DataParameter.Varchar("@whateverParamName", "whateverParamValue"))

Any guidance would be much appreciated.

Migrate linq2db wiki

linq2db wiki articles should reviewed and moved to articles in this repository (and removed from linq2db wiki) to improve out documentation site and get rid of documentation duplication

Update readme: System.Configuration

Your readme is outdated. .NET core supports System.Configuration so you can read app.config normally.

Also Microsoft.Extensions.Configuration is official core way of configuring things.

Fix all 3rd-party xref resolve issues

We should add missing xref map files to docfx.json or write own map, if it doesn't exist for required types

Move howto to main readme.md

Content of this file should be moved to root readme.md

Professional services offerings

My organisation is looking to integrate linq2db into our data access stack. Do any of the main contributors have capacity for some professional services work? What would be the best way to get in touch?