docs(readme): document workaround for XML schema collection xsd files#902
docs(readme): document workaround for XML schema collection xsd files#902nmummau wants to merge 1 commit intorr-wfm:masterfrom
Conversation
This is for issue rr-wfm#861 where we will recommend the workaround with no plans to implement full xsd support.
|
@DanielLoth does this documentation align with what worked for you as a manual workaround? |
|
|
||
| Wildcards are supported for all nodes (`Content`, `None`, etc.). For example, `<None Include="Directory\**" />`. | ||
|
|
||
| ## XML schema collections (`.xsd`) |
There was a problem hiding this comment.
I think this should be near the bottom of the file
There was a problem hiding this comment.
Maybe let's hold off on this until we have the dedicated docusaurus docs site -- and this will be on a dedicated page.
There was a problem hiding this comment.
This PR can sit open for a bit of time then until that docusaurus PR finalizes. And I'll work to "merge" this xsd workaround into those docs. Then, we can close this PR with a link to the better docs site as a reference.
There was a problem hiding this comment.
Pull request overview
Documents a recommended workaround for SQL Server XML schema collections when using MSBuild.Sdk.SqlProj, addressing Issue #861 where .xsd build includes are not handled like classic .sqlproj projects.
Changes:
- Added a README section explaining the current limitation around
.xsdbuild inputs for XML schema collections. - Provided a workaround using a
.sqlscript withCREATE XML SCHEMA COLLECTIONand an embedded XSD payload.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| CREATE XML SCHEMA COLLECTION [dbo].[XMLSchemaCollection1] | ||
| AS N'<?xml version="1.0" encoding="utf-16"?> | ||
| <xs:schema id="XMLSchemaCollection1" | ||
| xmlns:xs="http://www.w3.org/2001/XMLSchema"> |
There was a problem hiding this comment.
The guidance says to copy the .xsd contents into the N'...' literal, but many .xsd files include an XML declaration like encoding="utf-8". When passed as an NVARCHAR literal, SQL Server can fail XML parsing if the declaration encoding doesn’t match (typically you should remove the XML declaration entirely, or ensure it’s utf-16). Consider adding an explicit note about this to prevent copy/paste failures.
| </xs:schema>'; | ||
| ``` | ||
|
|
||
| In practice, the workaround is to copy the contents of the `.xsd` file into the `N'...'` string of a `CREATE XML SCHEMA COLLECTION` statement and include that `.sql` file in your project instead of the `.xsd` file. |
There was a problem hiding this comment.
Copying an .xsd into a N'...' string also requires escaping any single quotes by doubling them, and large schemas may exceed the 4,000-character NVARCHAR literal limit unless you split/concatenate (or otherwise construct an NVARCHAR(MAX) value). Adding a brief note about escaping and size limits would make this workaround more reliable in practice.
| In practice, the workaround is to copy the contents of the `.xsd` file into the `N'...'` string of a `CREATE XML SCHEMA COLLECTION` statement and include that `.sql` file in your project instead of the `.xsd` file. | |
| In practice, the workaround is to copy the contents of the `.xsd` file into the `N'...'` string of a `CREATE XML SCHEMA COLLECTION` statement and include that `.sql` file in your project instead of the `.xsd` file. If the schema content contains single quotes, escape them by doubling them (`''`). Also note that large schemas may exceed the 4,000-character `NVARCHAR` literal limit, in which case you will need to split and concatenate the string or otherwise construct an `NVARCHAR(MAX)` value. |
|
Discussion above. This PR can sit open for a bit of time then until that docusaurus PR finalizes. And I'll work to "merge" this xsd workaround into those docs. Then, we can close this PR with a link to the better docs site as a reference. |
|
@nmummau Interested in following up on this using the new docs structure? |
This is for issue #861 where we will recommend the workaround with, where it seems there are no plans to implement full xsd support.