Sistema di versioni per la documentazione SQL

Articolo
04/26/2023

Si applica a: SQL Server Database SQL di Azure Azure Synapse Analytics Piattaforma di strumenti analitici (PDW)

Questo articolo illustra il sistema di versioni per la documentazione SQL. Il sistema di versioni distingue i prodotti e le relative versioni e consente di scegliere il prodotto e la versione a cui si è interessati, visualizzando la documentazione appropriata.

Si applica ai prodotti

Sotto il titolo della maggior parte degli articoli relativi a SQL Server è riportata la dicitura Si applica a. Sulla stessa riga viene visualizzato un elenco di prodotti SQL per indicare se l'articolo è rilevante per il prodotto. Ad esempio, il prodotto SQL Server potrebbe essere indicato come rilevante, mentre il database SQL di Azure potrebbe essere indicato come irrilevante per l'articolo.

La riga Si applica a non distingue le versioni dei prodotti. Microsoft si impegna a evitare discrepanze tra la riga Si applica a e l'aspetto dei prodotti delle configurazioni del sistema di versioni.

Cronologia di set di file separati

Per SQL Server 2014 e versioni precedenti, ogni versione ha la propria copia separata completa dei file della documentazione. Ad esempio, la documentazione per SQL Server 2014 è iniziata come copia della documentazione per SQL Server 2012. La copia per la versione 2014 è stata quindi modificata durante il ciclo di sviluppo del prodotto.

Questo approccio adottato in precedenza implicava che, in caso di errore nella documentazione per la versione 2014, lo stesso errore poteva essere presente anche per le versioni 2012 e 2008. Ciò rendeva più difficile la correzione degli errori e la manutenzione generale.

Più versioni negli stessi file

Per questo e altri motivi, i file della documentazione per SQL Server 2016 sono validi anche per le versioni 2017, 2019 e probabilmente per <vNext>. Questo consolidamento è stato attuato perché ora si assegnano moniker di controllo delle versioni ai file della documentazione di SQL Server. I moniker di controllo delle versioni vengono assegnati, o sono incorporati in modo esplicito, a qualsiasi livello di granularità che risulti appropriato per ogni file della documentazione specificato.

Controllo delle versioni nell'interfaccia utente

Quando si visualizza un articolo della documentazione di SQL tramite il sito Web Docs, il moniker di controllo delle versioni attualmente selezionato è visibile sopra il sommario. Il controllo è un elenco a discesa.

Se si vuole visualizzare la documentazione per un'altra versione di SQL Server, fare clic sulla freccia di espansione all'estremità del moniker di controllo delle versioni corrente. Quindi fare clic per scegliere qualsiasi combinazione di prodotto e versione desiderata. Quando si fa clic su una versione diversa, la documentazione visualizzata cambia istantaneamente per mostrare le differenze per la nuova versione scelta. Possono esserci modifiche e possono non esserci, entrambi i casi sono comuni.

Parametro HTTPS view=

Ogni articolo il cui indirizzo Web inizia con https://learn.microsoft.com/sql/ ha un parametro denominato ?view= aggiunto all'indirizzo stesso. Il valore di questo parametro è il codice del moniker di controllo delle versioni.

Il codice del moniker nell'indirizzo https corrisponde sempre al nome del moniker visualizzato nel controllo delle versioni.

Prodotti, non edizioni

Edizioni

Negli anni Novanta e Duemila Microsoft SQL Server aveva un solo prodotto. Erano disponibili diverse edizioni di ogni versione di SQL Server, ad esempio le edizioni Developer ed Enterprise di SQL Server 2008. Le edizioni rappresentavano set di funzionalità leggermente diversi, ma il prodotto principale era lo stesso. Le nuove versioni di SQL Server possono avere ancora una vasta gamma di edizioni.

Prodotti

Con la più recente crescita del cloud computing e di Microsoft Azure, Microsoft ha rilasciato il prodotto Database SQL di Azure. Per quanto il prodotto tradizionale SQL Server locale e il prodotto Database SQL di Azure condividano molto codice, si tratta di due prodotti effettivamente distinti.

Per SQL, i moniker di controllo delle versioni fanno distinzione tra i prodotti, ma non tra le edizioni.

Prodotti SQL del cloud di Azure

Per quel che riguarda gli articoli i cui indirizzi Web iniziano con https://learn.microsoft.com/sql/, quasi tutti si applicano ad almeno una versione del prodotto denominato SQL Server. Un sottoinsieme di grandi dimensioni di questi articoli si applica anche a uno o più prodotti del servizio SQL ospitati nel cloud di Azure. Uno di questi prodotti del cloud SQL è denominato database SQL di Azure.

Naturalmente, il prodotto Database SQL di Azure ha una sola versione. Quasi tutti gli articoli che si applicano al database SQL di Azure, ma non a SQL Server, hanno indirizzi Web che iniziano con https://learn.microsoft.com/azure/sql-database/.

Scenari di filtraggio della versione

Il sistema di controllo delle versioni funziona escludendo tramite filtro tutto il contenuto della documentazione che non si applica al moniker correntemente attivo. Ogni volta che si sceglie un moniker di controllo delle versioni diverso, il set di contenuto nascosto cambia. Il filtro nasconde il contenuto ai livelli seguenti:

Sezioni o frasi in un articolo.
Voci per gli articoli nel sommario.

Di seguito sono riportati alcuni scenari che illustrano gli effetti della scelta di un moniker diverso.

Scenario 1: nell'articolo corrente

Lo scenario seguente è incentrato sulle sezioni all'interno dell'articolo corrente:

Il moniker di controllo delle versioni corrente è SQL Server 2017.
Si sta leggendo una sezione che descrive una funzionalità aggiunta per la prima volta alla versione 2017 di SQL Server.
Il moniker viene modificato in SQL Server 2016.
Si noterà che la sezione che si stava leggendo non è più disponibile.
Il moniker viene modificato nuovamente, questa volta in SQL Server 2019.
Si noterà che la sezione 2017 che si stava leggendo è di nuovo visualizzata.

Nello scenario precedente la sezione sulla nuova funzionalità 2017 probabilmente è contrassegnata con un intervallo di moniker che include il codice del moniker seguente:

>=sql-server-2017

Quando si è scelto il moniker SQL Server 2019, il sistema di controllo delle versioni ha realizzato che 2019 è maggiore di o uguale a 2017 e ha quindi visualizzato la sezione.

Scenario 2: clic su un collegamento a un articolo nascosto

Lo scenario non comune seguente spiega cosa accade se si fa clic su un collegamento a un articolo attualmente nascosto dal sommario. In breve, il collegamento funziona:

Il moniker di controllo delle versioni corrente è SQL Server 2017.
Nell'articolo corrente A si fa clic su un collegamento a un articolo B che si applica solo a SQL Server 2016.
- Prima di aver fatto clic, nel sommario la voce per l'articolo B è nascosta.
Dopo aver fatto clic, viene visualizzato l'articolo B.
- La visualizzazione dell'articolo B impone al controllo delle versioni di passare al moniker SQL Server 2016.
- Poiché è stato necessario abbandonare il moniker originale SQL Server 2017. Questo abbandono comporta la visualizzazione di un messaggio informativo nella parte superiore della pagina Web. Il messaggio spiega che è stato necessario cambiare il moniker corrente per supportare il nuovo articolo B.

Scenario 3: passaggio a un indirizzo https

L'articolo seguente è stato aggiunto nuovo per SQL Server 2017. L'articolo descrive le funzionalità aggiunte a SQL Server nella versione 2017. Tutte queste nuove funzionalità o buona parte di esse fanno parte anche della versione 2019. Ecco gli attributi dell'articolo.

Attributo	valore
Title	Novità di SQL Server 2017
intervallo di moniker	`=">= sql-server-2017"`
indirizzo `https`	`https://learn.microsoft.com/sql/sql-server/what-s-new-in-sql-server-2017`

Dato l'indirizzo https di base, la tabella seguente illustra cosa accade quando il parametro ?view= viene aggiunto dall'utente, con diversi valori.

Valore di `?view=`	Comportamento della navigazione all'indirizzo `https`
(Nessun parametro.)	Il sistema di controllo delle versioni proverà il valore del moniker predefinito. Questo valore viene in genere impostato sulla versione non di anteprima più recente di SQL Server. Un valore predefinito uguale a SQL Server 2017 o 2019 soddisferà l'attributo `>= sql-server-2017`. Il sistema aggiungerà il parametro all'indirizzo `https`, ad esempio nel formato `?view=sql-server-2017`. L'elenco a discesa di controllo delle versioni verrà quindi impostato sul nome del moniker corrispondente.
`sql-server-2016`	Il sistema di controllo delle versioni realizzerà che l'intervallo di moniker dell'articolo non include la versione 2016. Il sistema sceglierà quindi uno dei moniker che soddisfa l'intervallo. Come nel caso della versione 2016, verrà aggiunto il parametro `?view=` e il nome del controllo corrisponderà al valore del parametro.
`sql-server-2017`	Il sistema di controllo delle versioni comprende che il valore del parametro è incluso nell'intervallo di moniker dell'articolo. Il controllo delle versioni verrà impostato in modo da corrispondere al valore del parametro.
`sql-server-2019`	Uguale al caso del valore `sql-server-2017`, ad eccezione del fatto che il parametro e il controllo sono impostati su 2019.

Moniker speciale Tutto SQL - Visualizza tutto

Esiste un moniker speciale per il nome del prodotto All SQL (Tutto SQL) la cui unica versione è Hide nothing (Visualizza tutto). Lo scopo di questo moniker è il test interno di determinate modifiche. Se usato da un cliente, è probabile che questo moniker fornisca informazioni fuorvianti.

Alcuni articoli contengono informazioni relative a più versioni di SQL Server. Ogni moniker regolare nasconde le sezioni relative alle versioni che potrebbero altrimenti visualizzare informazioni non accurate, confuse o contraddittorie per la versione del moniker. Il moniker speciale All SQL (Tutto SQL) visualizza invece le sezioni relative a tutte le versioni e potrebbe non essere ovvio che potrebbero essere visualizzate informazioni non accurate.

Messaggio: La pagina richiesta non è disponibile per <moniker>

Lo scenario seguente comporta la visualizzazione di un messaggio informativo nella parte superiore della pagina Web Docs:

Attualmente il moniker di controllo delle versioni è SQL Server 2017.
Si sta leggendo un articolo pertinente per SQL Server 2017.
- L'articolo non è pertinente per il prodotto Database SQL di Azure.
Si tenta di cambiare il moniker in Azure SQL Database - current (Database SQL di Azure - corrente).
Si noterà che il tentativo è stato rifiutato e viene visualizzato un messaggio.

Al termine di questo scenario, verrà visualizzato il messaggio informativo seguente nella parte superiore della pagina Web Docs:

La pagina richiesta non è disponibile per Azure SQL Database - current (Database SQL di Azure - corrente). È stato eseguito il reindirizzamento alla versione più recente del prodotto per cui questa pagina è disponibile.

La versione più recente potrebbe escludere le versioni non ancora completamente rilasciate e in stato di anteprima.

Versioni precedenti di SQL Server

Il sistema di controllo delle versioni è completamente implementato per le versioni da SQL Server 2016 in avanti.

2012 e precedenti: il sistema di controllo non viene usato per SQL Server 2012 o versioni precedenti.
- Il moniker speciale SQL Server - older (precedente) è destinato a nascondere quasi tutti gli articoli, ad eccezione di pochi articoli di cui i clienti delle versioni precedenti potrebbero aver bisogno.
- Versioni precedenti di SQL Server, 2012-2005
2014: il sistema di controllo delle versioni è implementato a metà per SQL Server 2014. È possibile scegliere SQL Server 2014 nel controllo delle versioni e funziona. Tuttavia, internamente i file per la versione 2014 sono dedicati solo alla versione 2014, allo stesso modo in cui i file per la versione 2008 sono dedicati solo alla versione 2008.
- Documentazione offline di SQL Server 2014
2016 e successive: il sistema di controllo delle versioni è completamente implementato per SQL Server 2016 e versioni successive.
- Documentazione di SQL Server 2016 e versioni successive
- Documentazione offline di SQL Server 2016

Vedi anche

Versioni precedenti di SQL Server, 2014-2005
Guida all'esplorazione della documentazione di SQL Server
Come contribuire alla documentazione di SQL Server