Exemple de code C# : soumission d’applications avec options de jeu et bandes-annonces
Cet article fournit des exemples de code C# qui montrent comment utiliser l’API de soumission du Microsoft Store pour les tâches suivantes :
- Obtenir un jeton d’accès Azure AD à utiliser avec l’API de soumission au Microsoft Store.
- Créer une soumission d’applications
- Configurer des données de description dans le Store pour la soumission d’applications, y compris des options de description avancées de jeux et de bandes-annonces.
- Charger le fichier ZIP contenant les packages, les images de description et les fichiers de bande-annonce pour la soumission d’applications.
- Valider la soumission d’applications.
Vous pouvez passer en revue chaque exemple pour en savoir plus sur la tâche qu’elle illustre, ou vous pouvez générer tous les exemples de code de cet article dans une application console. Pour générer les exemples, créez une application console C# nommée DevCenterApiSample dans Visual Studio, copiez chaque exemple dans un fichier de code distinct dans le projet et générez le projet.
Prérequis
Ces exemples ont les exigences suivantes :
- Ajoutez une référence à l’assembly System.Web dans votre projet.
- Installez le package NuGet Newtonsoft.Json de Newtonsoft vers votre projet.
Créer une soumission d’applications
La CreateAndSubmitSubmissionExample classe définit une méthode publique Execute qui appelle d’autres exemples de méthodes pour utiliser l’API de soumission du Microsoft Store pour créer et valider une soumission d’application qui contient des options de jeu et une bande-annonce. Adaptez ce code en fonction de vos besoins :
- Affectez la variable
tenantIdà l’ID de locataire pour votre application et affectez les variablesclientIdetclientSecretà l’ID client et à la clé de votre application. Pour plus d’informations, consultez Comment associer une application Azure AD à votre compte de l’Espace partenaires - Affectez la variable
applicationIdà l’ID Store de l’application pour laquelle vous voulez créer une soumission.
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;
}
}
}
Obtenir un jeton d’accès Azure AD
La classe DevCenterAccessTokenClient définit une méthode d’assistance qui utilise vos valeurs tenantId, clientId et clientSecret pour créer un jeton d’accès Azure AD à utiliser avec l’API de soumission au 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éthodes d’assistance pour appeler l’API de soumission et charger des fichiers de soumission
La classe DevCenterClient définit des méthodes d’assistance qui appellent plusieurs méthodes dans l’API de soumission au Microsoft Store et chargent le fichier ZIP contenant les packages, les images de description et les fichiers de bande-annonce pour la soumission d’applications.
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;
}
}
}