Ejemplo de C#: envío de aplicación con opciones de juego y tráileres
En este artículo se proporcionan ejemplos de código de C# que muestran cómo usar la API de envío de Microsoft Store para estas tareas:
- Obtenga un token de acceso de Azure AD para usarlo con la API de envío de Microsoft Store.
- Crear un envío de aplicación
- Configure los datos de la descripción de la Store para el envío de aplicación, incluidas las opciones de descripciones avanzadas de juegos y avances.
- Cargue el archivo ZIP que contiene los paquetes, las imágenes de descripciones y los archivos de avances para el envío de aplicación.
- Confirme el envío de aplicación.
Puede revisar cada ejemplo para obtener más información sobre la tarea que muestra o puede compilar todos los ejemplos de código de este artículo en una aplicación de consola. Para compilar los ejemplos, cree una aplicación de consola de C# denominada DevCenterApiSample en Visual Studio, copie cada ejemplo en un archivo de código independiente del proyecto y compile el proyecto.
Requisitos previos
Estos ejemplos tienen los siguientes requisitos:
- Agregue una referencia al ensamblado System.Web en el proyecto.
- Instale el paquete NuGet Newtonsoft.Json desde Newtonsoft al proyecto.
Crear un envío de aplicación
La CreateAndSubmitSubmissionExample clase define un método público Execute que llama a otros métodos de ejemplo para usar la API de envío de Microsoft Store para crear y confirmar un envío de aplicación que contiene opciones de juego y un finalizador. Para adaptar este código a su propio uso:
- Asigne la variable
tenantIdal id. de inquilino para la aplicación y asigne las variablesclientIdyclientSecretal identificador de cliente y clave para la aplicación. Para obtener más información, consulte Asociación de una aplicación de Azure AD a la cuenta del Centro de partners - Asigne la variable
applicationIdal Id. de la Store de la aplicación para la cual quiere crear un envío.
using System;
using System.Threading;
using Newtonsoft.Json.Linq;
namespace DevCenterApiSample
{
public class CreateAndSubmitSubmissionExample
{
public static void Execute()
{
// Add your tenant ID, client ID, and client secret here.
string tenantId = "";
string clientId = "";
string clientSecret = "";
var accessTokenClient = new DevCenterAccessTokenClient(tenantId, clientId, clientSecret);
string accessToken = accessTokenClient.GetAccessToken("https://manage.devcenter.microsoft.com");
var devCenter = new DevCenterClient(accessToken);
// The application ID is taken from your app dashboard page's URI in Dev Center,
// e.g. https://developer.microsoft.com/en-us/dashboard/apps/{application_id}/
string applicationId = "{application_id}";
// Get the application object, and cancel any in progress submissions.
JObject app = devCenter.GetApplication(applicationId);
JToken inProgressSubmission = app.GetValue("pendingApplicationSubmission");
if (inProgressSubmission != null)
{
string inProgressSubmissionId = inProgressSubmission.Value<string>("id");
devCenter.CancelInProgressSubmission(applicationId, inProgressSubmissionId);
}
// Create a new submission, based on the last published submission.
JObject submission = devCenter.CreateSubmission(applicationId);
string submissionId = submission.GetValue("id").Value<string>();
// The following fields are required.
submission["applicationCategory"] = "Games_Fighting";
submission["listings"] = GetListingsObject();
submission["pricing"] = GetPricingObject();
submission["packages"] = new JArray() { GetPackageObject() };
submission["allowTargetFutureDeviceFamilies"] = GetDeviceFamiliesObject();
// The app must have the hasAdvancedListingPermission set to True in order for gaming options
// and trailers to be applied. If that's not the case, you can still update the app and
// its submissions through the API, but gaming options and trailers won't be saved.
if (app["hasAdvancedListingPermission"] == null || app["hasAdvancedListingPermission"].Value<bool>() == false)
{
Console.WriteLine("This application does not support gaming options or trailers.");
}
else
{
// Gaming options is an array. A maximum of one value may be provided.
submission["gamingOptions"] = new JArray(GetGamingOptionsObject());
// A maximum of 15 trailers may be provided in the trailers array.
submission["trailers"] = new JArray(GetTrailerObject());
}
// Continue updating the submission_json object with additional options as needed.
// After you've finished, call the Update API with the code below to save it.
JObject updatedSubmission = devCenter.UpdateSubmission(applicationId, submissionId, submission);
// All images and packages should be located in a single ZIP file. In the submission JSON,
// the file names for all objects requiring them (icons, packages, etc.) must exactly
// match the file names from the ZIP file.
string zipFilePath = "";
devCenter.UploadZipFileForSubmission(applicationId, submissionId, zipFilePath);
// Committing the submission will start the submission process for it. Once committed,
// the submission can no longer be changed.
devCenter.CommitSubmission(applicationId, submissionId);
// After committing, you can poll the commit API for the status of the submission's process using
// the following code.
bool waitingForCommitToStart = true;
while (waitingForCommitToStart)
{
string status = devCenter.GetSubmissionStatus(applicationId, submissionId);
Console.WriteLine($"Submission status: {status}");
waitingForCommitToStart = status.Equals("CommitStarted");
if (waitingForCommitToStart)
{
Thread.Sleep(TimeSpan.FromMinutes(1)); // Wait to check Dev Center again.
}
}
}
private static JObject GetListingsObject()
{
// This structure holds basic information to display in the store.
var baseListing = new JObject();
baseListing.Add("copyrightAndTrademarkInfo", "(C) 2017 Microsoft");
baseListing.Add("licenseTerms", "http://example.com/licenseTerms.aspx");
baseListing.Add("privacyPolicy", "http://example.com/privacyPolicy.aspx");
baseListing.Add("supportContact", "support@example.com");
baseListing.Add("websiteUrl", "http://example.com");
baseListing.Add("description", "A sample game showing off gameplay options code.");
baseListing.Add("releaseNotes", "Initial release");
// The title of the app must match a reserved name for the app in Dev Center.
// If it doesn't, attempting to update the submission will fail.
baseListing.Add("title", "Super Game Options API Simulator 2017");
var keywords = new JArray();
keywords.Add("SampleApp");
keywords.Add("SampleFightingGame");
keywords.Add("GameOptions");
baseListing.Add("keywords", keywords);
var features = new JArray();
features.Add("Doesn't crash");
features.Add("Likes to eat chips");
baseListing.Add("features", features);
// If your app works better with specific hardware (or needs it), you can
// add or update values here.
var hardwarePreferences = new JArray()
{
"Keyboard",
"Mouse"
};
baseListing.Add("hardwarePreferences", hardwarePreferences);
var images = new JArray();
// There are several types of images available; at least one screenshot
// is required.
var image = new JObject();
// The file name is relative to the root of the uploaded ZIP file.
image.Add("fileName", "img/screenshot.png");
image.Add("description", "A basic screenshot of the app.");
image.Add("imageType", "Screenshot");
images.Add(image);
baseListing.Add("images", images);
var listing = new JObject();
listing.Add("baseListing", baseListing);
// If there are any specific overrides to above information for Windows 8,
// Windows 8.1, Windows Phone 7.1, 8.0, or 8.1, you can add information here.
listing.Add("platformOverrides", new JObject());
// Each listing is targeted at a specific language-locale code, e.g. EN-US.
var listings = new JObject();
listings.Add("en-us", listing);
return listings;
}
private static JObject GetPackageObject()
{
var package = new JObject()
{
// The file name is relative to the root of the uploaded ZIP file.
["fileName"] = "bin/super_dev_ctr_api_sim.appxupload",
// If you haven't begun to upload the file yet, set this value to "PendingUpload".
["fileStatus"] = "PendingUpload"
};
return package;
}
private static JObject GetPricingObject()
{
var pricing = new JObject();
// How long the trial period is, if one is allowed. Valid values are NoFreeTrial,
// OneDay, SevenDays, FifteenDays, ThirtyDays, or TrialNeverExpires.
pricing.Add("trialPeriod", "NoFreeTrial");
// Maps to the default price for the app.
pricing.Add("priceId", "Free");
// If you'd like to offer your app in different markets at different prices, you
// can provide priceId values per language/locale code.
pricing.Add("marketSpecificPricing", new JObject());
return pricing;
}
private static JObject GetDeviceFamiliesObject()
{
var futureDeviceFamilies = new JObject();
// Supported values are Desktop, Mobile, Xbox, and Holographic. To make
// the app available on that specific platform, set the value to True.
futureDeviceFamilies.Add("Desktop", true);
futureDeviceFamilies.Add("Mobile", false);
futureDeviceFamilies.Add("Xbox", true);
futureDeviceFamilies.Add("Holographic", false);
return futureDeviceFamilies;
}
private static JObject GetTrailerObject()
{
// Add an example trailer.
var trailer = new JObject();
// This is the filename of the trailer. The file name is a relative path to the
// root of the ZIP file to be uploaded to the API.
trailer["VideoFileName"] = "trailers/main/my_awesome_trailer.mpeg";
// Aside from the video itself, a trailer can have image assets such as screenshots
// or alternate images.
var trailerAssets = new JObject();
trailer["TrailerAssets"] = trailerAssets;
// Add trailer assets for the EN-US market.
var trailerAsset = new JObject();
trailerAssets["en-us"] = trailerAsset;
// The title of the trailer to display in the store.
trailerAsset["Title"] = "Main Trailer";
// The list of images provided with the trailer that are shown
// when the trailer isn't playing.
var imageList = new JArray();
trailerAsset["ImageList"] = imageList;
// Add a few images to the image list.
var thumbnailImage = new JObject()
{
// The file name of the image. The file name is a relative
// path to the root of the ZIP
// file to be uploaded to the API.
["FileName"] = "trailers/main/thumbnail.png",
// A plaintext description of what the image represents.
["Description"] = "The thumbnail for the trailer shown " + "before the user clicks play"
};
imageList.Add(thumbnailImage);
var altImage = new JObject()
{
["FileName"] = "trailers/main/alt-img.png",
["Description"] = "The image to show after the trailer plays"
};
imageList.Add(altImage);
return trailer;
}
private static JObject GetGamingOptionsObject()
{
var gamingOptions = new JObject();
// The genres of your game.
var genres = new JArray();
genres.Add("Games_Fighting");
gamingOptions["genres"] = genres;
// Set this to true if your game supports local multiplayer. This field
// is required.
gamingOptions["isLocalMultiplayer"] = true;
// If local multiplayer is supported, you must provide the minimum and
// maximum players supported. Valid values are between 2 and 1000 inclusive.
gamingOptions["localMultiplayerMinPlayers"] = 2;
gamingOptions["localMultiplayerMaxPlayers"] = 4;
// Set this to True if your game supports local co-op play. This field is required.
gamingOptions["isLocalCooperative"] = true;
// If local co-op is supported, you must provide the minimum and maximum players
// supported. Valid values are between 2 and 1000 inclusive.
gamingOptions["localCooperativeMinPlayers"] = 2;
gamingOptions["localCooperativeMaxPlayers"] = 4;
// Set this to True if your game supports online multiplayer. This field is required.
gamingOptions["isOnlineMultiplayer"] = true;
// If online multiplayer is supported, you must provide the minimum and maximum players
// supported. Valid values are between 2 and 1000 inclusive.
gamingOptions["onlineMultiplayerMinPlayers"] = 2;
gamingOptions["onlineMultiplayerMaxPlayers"] = 4;
// Set this to true if your game supports online co-op play. This field is required.
gamingOptions["isOnlineCooperative"] = true;
// If online co-op is supported, you must provide the minimum and maximum players
// supported. Valid values are between 2 and 1000 inclusive.
gamingOptions["onlineCooperativeMinPlayers"] = 2;
gamingOptions["onlineCooperativeMaxPlayers"] = 4;
// If your game supports broadcasting a stream to other players, set this field to True.
// This field is required.
gamingOptions["isBroadcastingPrivilegeGranted"] = true;
// If your game supports cross-device play (e.g. a player can play on an Xbox One with
// their friend who's playing on a PC), set this field to True. This field is required.
gamingOptions["isCrossPlayEnabled"] = true;
// If your game supports Kinect usage, set this field to "Enabled", otherwise, set it to
// "Disabled". This field is required.
gamingOptions["kinectDataForExternal"] = "Disabled";
// Free text about any other peripherals that your game supports. This field is optional.
gamingOptions["otherPeripherals"] = "Supports the usage of all fighting joysticks.";
return gamingOptions;
}
}
}
Obtención de un token de acceso de Azure AD
La clase DevCenterAccessTokenClient define un método auxiliar que usa los valores tenantId, clientId y clientSecret para crear un token de acceso de Azure AD para usarlo con la API de envío de Microsoft Store.
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
namespace DevCenterApiSample
{
/// <summary>
/// A client for getting access tokens to the Dev Center API.
/// </summary>
public class DevCenterAccessTokenClient
{
private string _tenantId;
private string _clientId;
private string _clientSecret;
/// <summary>
/// Creates a new instance of the <see cref="DevCenterAccessTokenClient"/> class.
/// </summary>
/// <param name="tenantId">The AAD tenant ID.</param>
/// <param name="clientId">The AAD client ID.</param>
/// <param name="clientSecret">The AAD client secret.</param>
public DevCenterAccessTokenClient(string tenantId, string clientId, string clientSecret)
{
_tenantId = tenantId;
_clientId = clientId;
_clientSecret = clientSecret;
}
/// <summary>
/// Generates an access token to the specified resource URI.
/// </summary>
/// <param name="resource">The resource URI.</param>
/// <returns>An access token for authentication.</returns>
public string GetAccessToken(string resource)
{
// Generate access token. Access token is valid for 1 hour. Regenerate access token when needed
HttpRequestMessage tokenRequest = new HttpRequestMessage(HttpMethod.Post, $"https://login.microsoftonline.com/{_tenantId}/oauth2/token");
string tokenRequestBody = $"grant_type=client_credentials&client_id={_clientId}&client_secret={_clientSecret}&resource={resource}";
tokenRequest.Content = new StringContent(tokenRequestBody, Encoding.UTF8, "application/x-www-form-urlencoded");
HttpClient client = new HttpClient();
HttpResponseMessage response = client.SendAsync(tokenRequest).GetAwaiter().GetResult();
string responseBody = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
JObject responseJson = (JObject)JsonConvert.DeserializeObject(responseBody);
tokenRequest.Dispose();
client.Dispose();
response.Dispose();
return responseJson["access_token"].Value<string>() ?? string.Empty;
}
}
}
Métodos auxiliares para invocar la API de envío y cargar archivos de envío
La clase DevCenterClient define métodos auxiliares que invocan una variedad de métodos en la API de envío de Microsoft Store y cargan el archivo ZIP que contiene los paquetes, las imágenes de descripciones y los archivos de tráileres para el envío de aplicación.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Web;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.IO;
namespace DevCenterApiSample
{
/// <summary>
/// A client for accessing the Dev Center APIs.
/// </summary>
public class DevCenterClient
{
private string _accessToken;
private Uri _baseUri;
/// <summary>
/// Creates a new instance of the <see cref="DevCenterClient"/> class.
/// </summary>
/// <param name="accessToken">The access token to authenticate to the service with.</param>
public DevCenterClient(string accessToken)
{
_baseUri = new Uri("https://manage.devcenter.microsoft.com");
_accessToken = accessToken;
}
/// <summary>
/// Retrieves the JSON object representing the application from Dev Center.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <returns>A JObject that may be navigated.</returns>
/// <remarks>
/// The application ID is taken from your app dashboard page's URI in Dev Center,
/// e.g. https://developer.microsoft.com/en-us/dashboard/apps/{application_id}/
/// </remarks>
public JObject GetApplication(string applicationId)
=> Invoke(HttpMethod.Get, $"/v1.0/my/applications/{applicationId}");
/// <summary>
/// Cancels an in-progress submission for the app.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <returns></returns>
public void CancelInProgressSubmission(string applicationId, string submissionId)
=> Invoke(HttpMethod.Delete, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}");
/// <summary>
/// Creates a new in-progress submission for the application.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <returns>A JObject that may navigated.</returns>
public JObject CreateSubmission(string applicationId)
=> Invoke(HttpMethod.Post, $"/v1.0/my/applications/{applicationId}/submissions");
/// <summary>
/// Updates the submission with the new data provided.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <param name="submission">The submission body.</param>
/// <returns>The updated submission JObject.</returns>
public JObject UpdateSubmission(string applicationId, string submissionId, JObject submission)
=> Invoke(HttpMethod.Put, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}", submission);
/// <summary>
/// Gets the submission from Dev Center.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <returns>The submission object from Dev Center.</returns>
public JObject GetSubmission(string applicationId, string submissionId)
=> Invoke(HttpMethod.Get, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}");
/// <summary>
/// Commits the submission to Dev Center.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <remarks>
/// Once a submission is committed, Dev Center will begin processing and certifying it;
/// it can no longer be changed after this point.
/// </remarks>
public void CommitSubmission(string applicationId, string submissionId)
=> Invoke(HttpMethod.Post, $"/v1.0/my/applications/{applicationId}/submissions/{submissionId}/commit");
/// <summary>
/// Returns the current submission commit status.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <returns>The submission status.</returns>
public string GetSubmissionStatus(string applicationId, string submissionId)
{
JObject response = GetSubmission(applicationId, submissionId);
string status = response.Value<string>("status") ?? "Unknown";
return status;
}
/// <summary>
/// Uploads the ZIP file containing assets for the submission to the submission in Dev Center.
/// </summary>
/// <param name="applicationId">The application ID.</param>
/// <param name="submissionId">The submission ID.</param>
/// <param name="zipFilePath">The path to the ZIP file.</param>
public void UploadZipFileForSubmission(string applicationId, string submissionId, string zipFilePath)
{
JObject submission = GetSubmission(applicationId, submissionId);
string fileUploadUrl = submission["fileUploadUri"].Value<string>();
HttpRequestMessage uploadRequest = new HttpRequestMessage(HttpMethod.Put, fileUploadUrl.Replace("+", "%2B")); // Encode '+', otherwise it will be decoded as ' '
uploadRequest.Content = new StreamContent(File.OpenRead(zipFilePath));
uploadRequest.Headers.Add("x-ms-blob-type", "BlockBlob");
HttpClient httpClient = new HttpClient();
HttpResponseMessage uploadResponse = httpClient.SendAsync(uploadRequest).GetAwaiter().GetResult();
uploadResponse.EnsureSuccessStatusCode();
uploadRequest.Dispose();
uploadResponse.Dispose();
httpClient.Dispose();
}
private JObject Invoke(HttpMethod method, string path, JObject body = null)
{
HttpRequestMessage request = new HttpRequestMessage(method, new Uri(_baseUri, path));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _accessToken);
request.Headers.UserAgent.ParseAdd("C-Sharp");
if (body != null)
{
request.Content = new StringContent(body.ToString(), Encoding.UTF8, "application/json");
}
HttpClient client = new HttpClient();
HttpResponseMessage response = client.SendAsync(request).GetAwaiter().GetResult();
string responseContent = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
if (!response.IsSuccessStatusCode)
{
string message = string.IsNullOrEmpty(responseContent) ? response.ReasonPhrase : responseContent;
throw new HttpException((int)response.StatusCode, message);
}
if (string.IsNullOrEmpty(responseContent))
{
return null;
}
client.Dispose();
request.Dispose();
response.Dispose();
JObject responseObject = (JObject)JsonConvert.DeserializeObject(responseContent);
return responseObject;
}
}
}